diff --git a/README.md b/README.md index 76149512f6..0e2f5730d2 100644 --- a/README.md +++ b/README.md @@ -94,10 +94,16 @@ uvx --from git+https://github.com/github/spec-kit.git specify init ): explanation` marker and list it in the Sync Impact Report. -3. Draft the updated constitution content: +4. Draft the updated constitution content: - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left). - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance. - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. -4. Consistency propagation checklist (convert prior checklist into active validations): +5. Consistency propagation checklist (convert prior checklist into active validations): - Read `/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles. - Read `/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints. - Read `/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline). - Read each command file in `/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required. - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed. + - If `/memory/enterprise-constitution.md` exists and has been updated outside this command, ensure that any project-level references to enterprise principles still point to valid sections or concepts. -5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update): +6. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update): - Version change: old → new - List of modified principles (old title → new title if renamed) - Added sections - Removed sections - Templates requiring updates (✅ updated / ⚠ pending) with file paths + - Enterprise alignment summary: + - Whether the enterprise constitution was successfully retrieved from its canonical repository and whether `/memory/enterprise-constitution.md` was present/updated as a cache. + - Any project-level principles that narrow or extend enterprise rules. + - Any `TODO(CONFLICT_*)` items, with a short description. - Follow-up TODOs if any placeholders intentionally deferred. -6. Validation before final output: +7. Validation before final output: - No remaining unexplained bracket tokens. - Version line matches report. - Dates ISO format YYYY-MM-DD. - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate). + - No project-level rule silently contradicts the enterprise constitution; any suspected conflict is explicitly marked with a TODO and called out in the Sync Impact Report. -7. Write the completed constitution back to `/memory/constitution.md` (overwrite). +8. Write the completed constitution back to `/memory/constitution.md` (overwrite). -8. Output a final summary to the user with: +9. Output a final summary to the user with: - New version and bump rationale. - Any files flagged for manual follow-up. - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`). diff --git a/templates/commands/enterprise-constitution.md b/templates/commands/enterprise-constitution.md new file mode 100644 index 0000000000..fd712c64a5 --- /dev/null +++ b/templates/commands/enterprise-constitution.md @@ -0,0 +1,146 @@ +--- +description: Create or update the higher-level enterprise constitution that governs all project constitutions. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +You are updating the **enterprise constitution**, which is the **single source of truth** +for non‑negotiable, organization‑wide guiding principles and governance rules that all +project-level constitutions MUST obey. + +- The enterprise constitution defines global values, constraints, and guardrails. +- It is typically stored in a dedicated governance or platform repository and may be + **mirrored into individual projects** as a cached copy at `/memory/enterprise-constitution.md`. +- Every project constitution (for example `/memory/constitution.md`) is subordinate + to this document and MUST NOT contradict it. +- Projects MAY further narrow or strengthen enterprise rules, but they MUST NOT + weaken or violate them. + +## Outline + +Follow this execution flow: + +1. **Load existing enterprise constitution (if any)** + - Prefer loading from the **canonical governance repository** if its location + is known (e.g., Git repo URL + path, or an HTTP/HTTPS URL to the file). + - If you are working directly in that governance repo, load and parse the + local file there (which will typically also be mirrored at + `/memory/enterprise-constitution.md`). + - Identify its current version, ratification date, last amended date, and + existing principles and governance sections. + - If no existing enterprise constitution can be found, you are creating + version `1.0.0` of the enterprise constitution; ask the user (or infer) + core organizational values and constraints and propose a canonical + storage location (repository + file path). + +2. **Collect/derive principles and governance elements** + - Use user input first when it clearly expresses organization-wide values, + non-negotiable rules, or governance expectations. + - Otherwise, infer from repo context (e.g., `README.md`, `docs/*.md`, + security, compliance, and contribution guidelines) to propose a coherent + enterprise-level set of principles. + - Define a small number of crisp, testable principles (for example, + 5–10 core principles) grouped under clear headings such as: + - Mission & Outcomes + - Safety, Security & Compliance + - Quality & Reliability + - Transparency & Accountability + - Data & Privacy + - AI & Automation (if applicable) + - Delivery Discipline & Change Management (for example, small, + incremental, independently reviewable changes) + - For governance, define at least: + - Who can propose amendments. + - How changes are reviewed and approved. + - How often the constitution should be revisited. + - How conflicts with project-level constitutions are resolved. + - How work is expected to be sliced and delivered (for example, + small, focused tasks; narrow pull requests; and incremental, + revertible changes tied to clear Task and story IDs). + +3. **Decide version bump** + - If creating the constitution for the first time, set + `CONSTITUTION_VERSION` to `1.0.0` and `RATIFICATION_DATE` to the + organization’s chosen date (or `TODO(RATIFICATION_DATE)` if unknown). + - If updating an existing enterprise constitution, determine the new + semantic version: + - MAJOR: Backward-incompatible changes to core values or removal/ + redefinition of principles. + - MINOR: New principles or material expansions of governance. + - PATCH: Clarifications, wording, or non-semantic refinements. + - Set `LAST_AMENDED_DATE` to today (YYYY-MM-DD) if any changes are made; + otherwise keep the existing date. + +4. **Draft the updated enterprise constitution** + - Use clear Markdown structure with top-level sections like: + - Preamble + - Principles + - Governance + - Compliance & Review + - Each principle MUST: + - Have a short, specific name. + - State non‑negotiable rules using clear, declarative language. + - Provide a brief rationale if not obvious from the rule itself. + - Governance MUST explicitly state that: + - All project constitutions MUST comply with the enterprise constitution. + - Project constitutions MAY add stricter rules but not weaker ones. + - In case of conflict, the enterprise constitution prevails. + +5. **Produce an Enterprise Sync Impact Report** + - Prepend an HTML comment block at the top of the canonical enterprise constitution + file (and any mirrored `/memory/enterprise-constitution.md` copy, if used in this + context) containing: + - Version change: old → new. + - List of added, modified, and removed principles. + - Governance changes. + - Where the canonical file is stored (repository + path, and commit/ref if known). + - Any `TODO(...)` fields and why they were deferred. + - This report is for humans; keep it concise and factual. + +6. **Validation before final output** + - Ensure dates use ISO format `YYYY-MM-DD`. + - Ensure principles are: + - Declarative and testable. + - Free of vague language (avoid "just", "try", etc.). + - Clearly applicable across all projects under the organization. + - Ensure governance clearly describes how project-level constitutions are + expected to align and how conflicts are handled. + +7. **Write or propose the completed enterprise constitution** + - If you are running inside the canonical governance repository: + - Overwrite the canonical enterprise constitution file with the fully + rendered Markdown, including the Enterprise Sync Impact Report comment + at top. + - If this environment also uses `/memory/enterprise-constitution.md` as a + mirror, update that file to match. + - If you are running inside a **consumer/project repository** (not the + canonical governance repo): + - Do **not** attempt to directly modify the remote canonical file. + - Instead, generate: + - The full updated enterprise constitution Markdown. + - A clear, minimal patch or PR description that can be applied to the + canonical repository (including target repo, file path, and a concise + change summary if known). + - Optionally write `/memory/enterprise-constitution.md` in this project as + a **temporary mirror** of the proposed new version, clearly marking in + the Enterprise Sync Impact Report that these changes are "pending + upstream approval" in the canonical repo. + +8. **Final summary to the user** + - Report the new version and bump rationale. + - Highlight the key enterprise principles that were added or changed. + - Call out any TODOs requiring organizational input (e.g., ratification body, + dates, or unresolved governance details). + - Explicitly state whether you: + - Updated the canonical file (when in the governance repo), or + - Generated a patch/PR proposal that must be applied in the canonical repo. + - Suggest a commit message such as: + `docs: establish enterprise constitution vX.Y.Z (org-wide principles)`. diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 3c952d683e..d6ea71e8f8 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -72,6 +72,14 @@ Given that feature description, do this: - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot") 3. Load `templates/spec-template.md` to understand required sections. + - Pay special attention to the "Project Context", "Related User Stories", + and "Related Implementation Tasks" sections: + - "Project Context" should reference a canonical project description + document (for example: docs/project-description.md) when available. + - "Related User Stories" should list external story IDs and links from + systems like GitHub Issues or Azure DevOps work items. + - "Related Implementation Tasks" should list external task IDs and links + (e.g., ADO child tasks) when they already exist. 4. Follow this execution flow: @@ -79,6 +87,10 @@ Given that feature description, do this: If empty: ERROR "No feature description provided" 2. Extract key concepts from description Identify: actors, actions, data, constraints + If the user has provided external story or task IDs (for example, + GitHub issues, Azure DevOps work items), collect them and plan to + populate the "Related User Stories" and "Related Implementation Tasks" + tables in the spec instead of duplicating story text. 3. For unclear aspects: - Make informed guesses based on context and industry standards - Only mark with [NEEDS CLARIFICATION: specific question] if: @@ -87,17 +99,28 @@ Given that feature description, do this: - No reasonable default exists - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total** - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details - 4. Fill User Scenarios & Testing section + 4. Fill Project Context and linking sections (when information provided) + - If a canonical project description document exists (for example, + docs/project-description.md), reference it briefly in the + "Project Context" section instead of rewriting it. + - If the user has supplied or you can infer external story IDs, add + them to the "Related User Stories" table with their system, ID, + short title, and link. + - If the user has supplied or you can infer external task IDs linked + to those stories, add them to the "Related Implementation Tasks" + table with their system, story ID, task ID, short title, and link. + + 5. Fill User Scenarios & Testing section If no clear user flow: ERROR "Cannot determine user scenarios" - 5. Generate Functional Requirements + 6. Generate Functional Requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in Assumptions section) - 6. Define Success Criteria + 7. Define Success Criteria Create measurable, technology-agnostic outcomes Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) Each criterion must be verifiable without implementation details - 7. Identify Key Entities (if data involved) - 8. Return: SUCCESS (spec ready for planning) + 8. Identify Key Entities (if data involved) + 9. Return: SUCCESS (spec ready for planning) 5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings. diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index d69d43763e..2f9df0c4a5 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -27,17 +27,23 @@ You **MUST** consider the user input before proceeding (if not empty). 1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). 2. **Load design documents**: Read from FEATURE_DIR: - - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities) + - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities and external links) - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios) - Note: Not all projects have all documents. Generate tasks based on what's available. 3. **Execute task generation workflow**: - Load plan.md and extract tech stack, libraries, project structure - - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.) + - Load spec.md and extract: + - User stories with their priorities (P1, P2, P3, etc.) + - Any external story IDs and links from the "Related User Stories" section + - Any external task IDs and links from the "Related Implementation Tasks" section - If data-model.md exists: Extract entities and map to user stories - If contracts/ exists: Map endpoints to user stories - If research.md exists: Extract decisions for setup tasks - - Generate tasks organized by user story (see Task Generation Rules below) + - Generate tasks organized by user story (see Task Generation Rules below) + - When external task IDs already exist for a given story, reference them in + the task description instead of inventing new identifiers (the external + system remains the source of truth for task state and ownership) - Generate dependency graph showing user story completion order - Create parallel execution examples per user story - Validate task completeness (each user story has all needed tasks, independently testable) @@ -65,7 +71,7 @@ You **MUST** consider the user input before proceeding (if not empty). Context for task generation: {ARGS} -The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context. +The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context. When online systems (GitHub, Azure DevOps, etc.) already contain tasks, use their IDs as references in the description and do not attempt to model or change their workflow states here. ## Task Generation Rules @@ -100,6 +106,7 @@ Every task MUST strictly follow this format: - ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py` - ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py` - ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py` +- ✅ CORRECT: `- [ ] T020 [US2] ADO-2001 Implement API endpoint for story ADO-1234 in src/api/feature_a.ts` - ❌ WRONG: `- [ ] Create User model` (missing ID and Story label) - ❌ WRONG: `T001 [US1] Create model` (missing checkbox) - ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID) @@ -138,3 +145,16 @@ Every task MUST strictly follow this format: - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration - Each phase should be a complete, independently testable increment - **Final Phase**: Polish & Cross-Cutting Concerns + +### External Story and Task Systems + +- Systems like GitHub and Azure DevOps remain the **source of truth** for + user stories and implementation tasks, including their workflow states. +- When generating tasks.md: + - Reference external IDs (e.g., GH-123, ADO-2001) in task descriptions when + those tasks already exist. + - Do **not** attempt to manage or duplicate state transitions (New, Active, + In Progress, Done, etc.) inside tasks.md. Those transitions happen in the + external system. + - Use tasks.md to provide implementation structure, file paths, and grouping + by user story, not to replace the external task board. diff --git a/templates/spec-template.md b/templates/spec-template.md index c67d914980..5cb3f22830 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -5,6 +5,45 @@ **Status**: Draft **Input**: User description: "$ARGUMENTS" +## Project Context *(optional but recommended)* + + + +- Project description source: [link or file path] +- Key goals this feature supports: + - [Goal 1] + - [Goal 2] + +## Related User Stories *(optional)* + + + +| System | Story ID | Title (short) | Link | +| ------------ | -------- | ------------- | ---- | +| [GitHub/ADO] | [1234] | [Short title] | [URL]| + +## Related Implementation Tasks *(optional)* + + + +| System | Story ID | Task ID | Task Title | Link | +| ------------ | -------- | ------- | ---------------- | ---- | +| [GitHub/ADO] | [1234] | [2001] | [Implement X...] | [URL]| + ## User Scenarios & Testing *(mandatory)*