Spec Kit Integration Details

This document explains the integration introduced in commit c906ed7 ("feat: integrated spec-kit into repo"), covering added assets, their roles, and how to extend them.

Summary of Added Paths

Prompt Files

Prompts are colocated under .github/prompts/ so GitHub Copilot Chat can easily ingest them when referencing the repository context. Each prompt file encodes:

• Role framing: e.g., treat the model as a rigorous architect vs. product analyst.
• Output contract: required sections, formatting expectations.
• Guardrails: avoid implementation details too early, ensure explicit assumptions list.

Customization Guidelines

Keep prompts concise enough to avoid token bloat while retaining determinism.

Constitution

memory/constitution.md encodes durable principles (security posture, architectural preferences, coding conventions). The goal: centralize guidance so AI outputs reflect institutional standards without re-stating them per prompt.

Use memory/constitution_update_checklist.md before editing to:

• Verify change justification
• Communicate impact (e.g., requires regenerating plans?)
• Version or annotate amendments (consider adding a Changelog section)

Good Constitution Entries

• Stable & strategic (e.g., "All external HTTP calls must pass through a typed gateway layer")
• Non-transient (avoid sprint-specific items)
• Testable or reviewable (code reviewers can enforce)

Templates

Templates ensure generated artifacts are uniform, increasing readability & diffability. They reduce accidental omission of critical sections.

Scripts Overview

Scripts accelerate consistent usage across contributors and can be integrated into CI or local automations.

create-new-feature.sh

Likely flow (extend as needed):

1. Accept feature slug / human-readable name.
2. Create directories: specs/, plans/, tasks/ if missing.
3. Copy templates with substituted placeholders (title/date/slug).
4. Optionally open spec in editor.

setup-plan.sh

Purpose: Gather context before invoking /plan, e.g.:

• Enumerate relevant existing services/modules
• Collect data schema references
• Output a summary file the agent can read

update-agent-context.sh

Future enhancement candidate: produce embeddings or summarizations (e.g., component maps) to reduce hallucination.

check-task-prerequisites.sh

Prevents starting implementation when prerequisites (migrations, environment variables, running services) are missing.

Suggested Directory Conventions (Adopt Incrementally)

/specs
  feature-workspace-sharing.md
/plans
  feature-workspace-sharing-plan.md
/tasks
  feature-workspace-sharing-tasks.md

Add an index file per directory if browsing grows.

Integration Validation Checklist

Next Hardening Steps

1. Add CI lint to enforce presence of required sections in new spec/plan/task PRs.
2. Introduce artifact changelog sections to track evolution.
3. Add script to diff two plan versions (for alternative exploration).
4. Incorporate minimal test generation hints per task.
5. Provide a make feature slug=<...> wrapper for ergonomics.

Decision Log (Start Here)

(Extend this table as process evolves.)

Proceed to Customization & Best Practices for extending this toolkit.