Skip to content

Commit 2b68227

Browse files
cityaccityac
committed
Add autonomous pipeline infrastructure
Autonomous clarification protocol, spec quality gate checklist, pipeline command template, and decisions log template. These enable fully autonomous specify-through-implement runs with convention-based quality gates that halt on unresolvable blockers.
1 parent 480f761 commit 2b68227

File tree

4 files changed

+323
-0
lines changed

4 files changed

+323
-0
lines changed

‎memory/autonomous-constitution.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
## Autonomous Clarification Protocol
2+
3+
After every `/speckit.specify` run, before proceeding to planning, the agent MUST:
4+
5+
1. Re-read the generated `spec.md` in full.
6+
2. Adopt the role of a skeptical Product Manager and identify all requirements that are:
7+
- Ambiguous (could be interpreted in more than one way)
8+
- Missing (implied by context but not stated)
9+
- Contradictory (two requirements conflict with each other)
10+
3. For each issue found, resolve it using the most conservative and safe interpretation.
11+
4. Document every resolution in `.specify/specs/<feature>/decisions.md` using this format:
12+
13+
```
14+
### Decision: <short title>
15+
**Issue:** <what was ambiguous/missing/contradictory>
16+
**Resolution:** <what was decided>
17+
**Rationale:** <why this interpretation was chosen>
18+
```
19+
20+
5. Do NOT ask for human input. Do NOT pause. Resolve all issues autonomously and document them.
21+
6. Only proceed to `/speckit.plan` once `decisions.md` has been written and all open issues are resolved.
22+
23+
## Spec Quality Gate
24+
25+
After writing `decisions.md` and before running `/speckit.plan`, the agent MUST run `/speckit.checklist` against the criteria in `.specify/memory/quality-gate.md`.
26+
27+
For each checklist item:
28+
- Mark PASS or FAIL with a one-line rationale.
29+
- If any item FAILS: fix `spec.md` immediately, then re-run the checklist.
30+
- Repeat until all items PASS.
31+
- Do NOT proceed to planning with any failing items.
32+
- Do NOT ask for human review. Fix and re-score autonomously.
33+
34+
Record the final checklist scores in `.specify/specs/<feature>/quality-report.md`.
35+
36+
## Task Structural Validation
37+
38+
After running `/speckit.tasks` and before running `/speckit.implement`, the agent MUST validate `tasks.md` against all of the following rules:
39+
40+
**Coverage:**
41+
- Every user story in `spec.md` maps to at least one task in `tasks.md`.
42+
- Every acceptance criterion in `spec.md` is addressed by at least one task.
43+
44+
**Structure:**
45+
- Every task specifies at least one target file path.
46+
- Every task has a clear, unambiguous success condition.
47+
- No task contains open questions or unresolved references.
48+
49+
**Ordering:**
50+
- No task has a dependency on a task that appears after it in the list.
51+
- Tasks marked `[P]` (parallel) do not share write targets with each other.
52+
53+
**Autonomy check:**
54+
- Read every task and ask: "Can this task be implemented without human input?"
55+
- If any task requires human input to proceed, either resolve the blocker using available context or add it to a `blockers.md` file and halt (notify human).
56+
57+
If any validation rule fails: fix `tasks.md` and re-validate. Do not proceed with a broken task list.
58+
59+
## Pre-Flight Assertions Before Implementation
60+
61+
Before executing `/speckit.implement`, assert ALL of the following. If any assertion fails, halt and report — do NOT proceed:
62+
63+
- [ ] `constitution.md` exists and was referenced during spec and planning phases.
64+
- [ ] `spec.md` exists and has no unchecked checklist items.
65+
- [ ] `decisions.md` exists and documents all assumption resolutions.
66+
- [ ] `quality-report.md` exists and shows all items PASSING.
67+
- [ ] `tasks.md` passed all structural validations (coverage, structure, ordering, autonomy).
68+
- [ ] No `blockers.md` exists with unresolved items.
69+
70+
If all assertions pass: proceed with `/speckit.implement` without waiting for human confirmation.
71+
If any assertion fails: create or update `blockers.md` with the specific failure, then halt and notify.
72+
73+
## E2E Validation Protocol
74+
75+
After `/speckit.implement` and before committing:
76+
77+
1. Run `/speckit.e2e` to generate and run E2E tests from `spec.md` acceptance criteria.
78+
2. Tests use existing project test infrastructure if available.
79+
3. Reuse page objects and helpers — only extend, don't duplicate.
80+
4. 3 fix-and-retry cycles max — then write `blockers.md` and halt.
81+
5. Skip for backend-only features (no frontend files in `plan.md`).

‎memory/quality-gate.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Spec Quality Gate
2+
3+
This checklist is used by the agent to self-score every specification before planning begins.
4+
All items must PASS before proceeding. Fix and re-score if any item fails.
5+
6+
## Completeness
7+
8+
- [ ] Every feature mentioned in the prompt has at least one user story.
9+
- [ ] Every user story has at least one measurable acceptance criterion (not vague like "works correctly").
10+
- [ ] All happy-path flows are fully described end-to-end.
11+
- [ ] At least the most likely edge cases and error states are enumerated per user story.
12+
- [ ] No user story uses "should" without an explicit rationale for why it is optional.
13+
14+
## Clarity
15+
16+
- [ ] No requirement can be interpreted in more than one way without an explicit decision documented in `decisions.md`.
17+
- [ ] All referenced entities (users, roles, objects, states) are defined in the spec or in a glossary.
18+
- [ ] No requirement references external documents or context that is not available in the repo.
19+
20+
## Consistency
21+
22+
- [ ] No two requirements contradict each other.
23+
- [ ] Terminology is consistent throughout the spec (no synonyms for the same concept).
24+
- [ ] User stories are consistent with the governing principles in `constitution.md`.
25+
26+
## Implementability
27+
28+
- [ ] Every acceptance criterion is verifiable by a test or a deterministic check.
29+
- [ ] No acceptance criterion requires subjective human judgment to evaluate.
30+
- [ ] The spec does not prescribe implementation details that belong in the plan, not the spec.
31+
32+
## API & Integration (if applicable)
33+
34+
- [ ] Every API interaction specifies both success responses and error states.
35+
- [ ] No API contract leaves authentication, authorization, or rate limiting undefined if applicable.

‎templates/commands/pipeline.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
description: Run the full autonomous speckit pipeline — specify through implement with quality gates.
3+
scripts:
4+
sh: scripts/bash/check-prerequisites.sh --json --paths-only
5+
ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
6+
---
7+
8+
## User Input
9+
10+
```text
11+
$ARGUMENTS
12+
```
13+
14+
The user input is the **feature description** (required). Optional flags:
15+
- `--commit` — after implementation, create a git commit, push, and open a PR
16+
17+
Parse the arguments: extract the feature description text and whether `--commit` is present.
18+
19+
## Goal
20+
21+
Run the complete speckit pipeline autonomously — from specification through implementation — with convention-based quality gates. No human checkpoints. Halts only on unresolvable blockers (writes `blockers.md`).
22+
23+
## Execution Steps
24+
25+
### 1. Initialize
26+
27+
Run `{SCRIPT}` once from repo root to get `REPO_ROOT`.
28+
29+
Extract the feature description and `--commit` flag from user input.
30+
31+
### 2. Specify
32+
33+
Run `/speckit.specify {feature-description}`.
34+
35+
This creates the feature branch, spec directory, and `spec.md`.
36+
37+
### 3. Resolve Feature Directory
38+
39+
Re-run `{SCRIPT}` (without `--require-tasks`) to get `FEATURE_DIR` now that the feature branch and spec exist.
40+
41+
### 4. Convention Detection
42+
43+
Check which autonomous infrastructure is available:
44+
45+
```
46+
AUTONOMOUS_CONSTITUTION = exists(".specify/memory/autonomous-constitution.md")
47+
— OR constitution.md contains "## Autonomous Clarification Protocol"
48+
QUALITY_GATE = exists(".specify/memory/quality-gate.md")
49+
DECISIONS_TEMPLATE = exists(".specify/templates/decisions-template.md")
50+
PLAYWRIGHT_CONFIG = exists("playwright.config.js") OR exists("playwright.config.ts")
51+
E2E_SKILL = /speckit.e2e is available as a skill
52+
```
53+
54+
Each gate is independently enabled. Missing infrastructure means that gate is skipped (not an error).
55+
56+
### 5. Self-Clarification Loop (if AUTONOMOUS_CONSTITUTION)
57+
58+
Read `autonomous-constitution.md` (or the autonomous sections in `constitution.md`) for the clarification protocol.
59+
60+
1. Re-read the generated `spec.md` in full.
61+
2. Adopt the role of a skeptical Product Manager — identify ambiguous, missing, or contradictory requirements.
62+
3. For each issue, resolve using the most conservative interpretation.
63+
4. Write all resolutions to `{FEATURE_DIR}/decisions.md` (use `decisions-template.md` if available).
64+
5. Do NOT ask for human input. Resolve autonomously.
65+
66+
### 6. Quality Gate Loop (if QUALITY_GATE)
67+
68+
Read `.specify/memory/quality-gate.md`.
69+
70+
1. Score `spec.md` against every checklist item — mark PASS or FAIL with a one-line rationale.
71+
2. For each FAIL: fix `spec.md` immediately.
72+
3. Re-score until all items PASS.
73+
4. Write final scores to `{FEATURE_DIR}/quality-report.md`.
74+
75+
If after 3 full cycles any item still fails: write `{FEATURE_DIR}/blockers.md` and **halt**.
76+
77+
### 7. Plan
78+
79+
Run `/speckit.plan`.
80+
81+
### 8. Tasks
82+
83+
Run `/speckit.tasks`.
84+
85+
### 9. Task Structural Validation (if AUTONOMOUS_CONSTITUTION)
86+
87+
Read the Task Structural Validation section from `autonomous-constitution.md` (or `constitution.md`).
88+
89+
Validate `tasks.md` against:
90+
91+
**Coverage:**
92+
- Every user story in `spec.md` maps to at least one task.
93+
- Every acceptance criterion is addressed by at least one task.
94+
95+
**Structure:**
96+
- Every task specifies at least one target file path.
97+
- Every task has a clear success condition.
98+
- No open questions or unresolved references.
99+
100+
**Ordering:**
101+
- No dependency on a later task.
102+
- Parallel tasks `[P]` don't share write targets.
103+
104+
**Autonomy:**
105+
- Every task can be implemented without human input.
106+
107+
If validation fails: fix `tasks.md` and re-validate. If still failing after 3 cycles: write `{FEATURE_DIR}/blockers.md` and **halt**.
108+
109+
### 10. Pre-Flight Assertions (if AUTONOMOUS_CONSTITUTION)
110+
111+
Read the Pre-Flight Assertions section. Assert ALL of:
112+
113+
- [ ] `constitution.md` exists
114+
- [ ] `spec.md` exists and has no unchecked items
115+
- [ ] `decisions.md` exists (if self-clarification was enabled)
116+
- [ ] `quality-report.md` exists and all PASS (if quality gate was enabled)
117+
- [ ] `tasks.md` passed structural validation (if task validation was enabled)
118+
- [ ] No `blockers.md` with unresolved items
119+
120+
If any fail: write `{FEATURE_DIR}/blockers.md` and **halt**.
121+
122+
### 11. Implement
123+
124+
Run `/speckit.implement`.
125+
126+
### 12. E2E Tests (conditional)
127+
128+
**Only if** ALL of these are true:
129+
- PLAYWRIGHT_CONFIG exists
130+
- E2E_SKILL is available
131+
- `plan.md` references frontend files (e.g., files under `client/src/`, `src/pages/`, `src/components/`)
132+
133+
Then run `/speckit.e2e`.
134+
135+
If tests fail after 3 retry cycles: write `{FEATURE_DIR}/blockers.md` and **halt**.
136+
137+
**Skip** if any condition is false (not an error — just skip silently).
138+
139+
### 13. Commit and PR (if --commit flag)
140+
141+
1. Use the `/commit` skill to create the git commit. Do NOT create commits manually.
142+
2. Push the branch: `git push -u origin HEAD`
143+
3. Create PR: `gh pr create --fill`
144+
145+
If `/commit` skill is not available, fall back to manual `git add` + `git commit`.
146+
147+
### 14. Report
148+
149+
Display a summary of what was done:
150+
151+
```
152+
## Pipeline Complete: {feature-description}
153+
154+
### Steps Executed
155+
- [x] Specify — spec.md created
156+
- [x] Self-clarification — decisions.md ({N} decisions) [or: skipped — no autonomous constitution]
157+
- [x] Quality gate — all items PASS [or: skipped — no quality-gate.md]
158+
- [x] Plan — plan.md created
159+
- [x] Tasks — tasks.md created ({N} tasks)
160+
- [x] Task validation — all rules pass [or: skipped]
161+
- [x] Pre-flight — all assertions pass [or: skipped]
162+
- [x] Implement — all tasks executed
163+
- [x] E2E — tests pass [or: skipped — no playwright config / backend-only]
164+
- [x] Commit + PR — {PR_URL} [or: skipped — no --commit flag]
165+
166+
### Artifacts
167+
- Spec: {FEATURE_DIR}/spec.md
168+
- Decisions: {FEATURE_DIR}/decisions.md
169+
- Quality report: {FEATURE_DIR}/quality-report.md
170+
- Plan: {FEATURE_DIR}/plan.md
171+
- Tasks: {FEATURE_DIR}/tasks.md
172+
```
173+
174+
## Halting Protocol
175+
176+
At no point during steps 1-13 should the agent pause for human input.
177+
178+
If an unresolvable blocker is hit at any step:
179+
1. Write `{FEATURE_DIR}/blockers.md` with the specific failure and context.
180+
2. Display the blocker to the user.
181+
3. **Stop.** Do not continue to the next step.
182+
183+
Never ask for human clarification mid-pipeline. Resolve autonomously or halt.
184+
185+
## Operating Principles
186+
187+
- **Convention over configuration** — the pipeline auto-detects available infrastructure. No flags needed to enable gates.
188+
- **Graceful degradation** — missing infrastructure means the gate is skipped, not failed. A project with zero autonomous files still runs: specify → plan → tasks → implement.
189+
- **Fail fast, fail loud** — blockers halt immediately with a clear report. No silent failures.
190+
- **Idempotent gates** — each validation loop has a max retry count (3). Infinite loops are impossible.

‎templates/decisions-template.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Decisions Log — <Feature Name>
2+
3+
This file documents every assumption and resolution made during autonomous spec clarification.
4+
It serves as the audit trail for decisions made without human input.
5+
6+
## Format
7+
8+
### Decision: <short title>
9+
**Issue:** <what was ambiguous, missing, or contradictory>
10+
**Resolution:** <what was decided>
11+
**Rationale:** <why this interpretation — usually: most conservative, most consistent with constitution, most user-safe>
12+
13+
---
14+
15+
## Decisions
16+
17+
<!-- Agent populates this section during self-clarification -->

0 commit comments

Comments
 (0)