azclaude-copilot 0.4.10 → 0.4.13

package/templates/commands/blueprint.md

@@ -29,9 +29,33 @@ $ARGUMENTS
 
 ---
 
-## Step 1: Clarify (if needed)
+## Step 1: Spec Detection + Clarify
 
-If $ARGUMENTS is vague, use **AskUserQuestion**:
+First check if $ARGUMENTS is a spec file:
+```bash
+[ -f "$ARGUMENTS" ] && grep -q "Acceptance Criteria" "$ARGUMENTS" && echo "spec-file" || echo "inline"
+```
+
+**If spec file detected** (`.claude/specs/*.md`):
+1. Spawn `spec-reviewer` agent to validate quality:
+   ```
+   Validate this spec file before I use it to generate plan.md: {spec-file-path}
+   ```
+2. If verdict = `APPROVED` → read spec directly as the source of truth. Skip AskUserQuestion.
+   - Extract acceptance criteria → use as milestone completion criteria
+   - Extract data model / API changes → use as Files: hints
+   - Extract out-of-scope → use to exclude from milestones
+3. If verdict = `NEEDS_CLARIFY` → stop: `Run /clarify {spec-file} first, then retry /blueprint`
+4. If spec-reviewer not installed → read spec file directly, proceed without validation
+
+**If inline description** (not a spec file):
+- Check if `.claude/specs/` has a spec matching $ARGUMENTS keywords:
+  ```bash
+  ls .claude/specs/ 2>/dev/null | grep -i "$(echo "$ARGUMENTS" | cut -d' ' -f1-2)"
+  ```
+- If matching spec found → use it. If not → proceed with AskUserQuestion below.
+
+If $ARGUMENTS is vague (and no spec found), use **AskUserQuestion**:
 - What is the goal? (the problem, not the solution)
 - Any hard constraints? (backwards compatibility, performance, deadline)
 - What's explicitly out of scope?
@@ -77,6 +101,26 @@ State the risk level. If risk = high → recommend `EnterWorktree` during implem
 
 ---
 
+## Step 3b: Constitution Check + Task Graph
+
+After writing the plan (Step 3), check:
+```bash
+[ -f .claude/constitution.md ] && echo "constitution=found" || echo "no constitution"
+```
+
+If constitution found → scan plan steps against non-negotiables:
+- Read `## Non-Negotiables` from constitution.md
+- Flag any plan step that could violate a rule
+- Add a note to flagged steps: `⚠ Constitution check: may conflict with "{rule}" — verify before implementing`
+
+Then run `/tasks` to show dependency waves:
+```
+Next: Run /tasks to see which plan steps can run in parallel
+```
+(Do not block — /tasks is informational at this stage)
+
+---
+
 ## Step 4: Approval Gate
 
 **ExitPlanMode**
@@ -93,6 +137,42 @@ Tasks are only created after explicit approval. This is the point of /blueprint.
 
 ---
 
+## Feature-Scoped Mode (Optional)
+
+When $ARGUMENTS points to a spec file (`.claude/specs/*.md`) OR contains a named feature:
+
+```bash
+# Detect spec file
+[ -f "$ARGUMENTS" ] && echo "spec-mode" || echo "inline-mode"
+
+# Determine next feature number
+NEXT_N=$(ls .claude/features/ 2>/dev/null | grep -c '^' || echo 0)
+N=$(printf '%02d' $((NEXT_N + 1)))
+SLUG=$(basename "$ARGUMENTS" .md 2>/dev/null || echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-40)
+FEATURE_DIR=".claude/features/${N}-${SLUG}"
+```
+
+If spec file provided → create a feature-scoped directory:
+```bash
+mkdir -p "$FEATURE_DIR"
+cp "$ARGUMENTS" "$FEATURE_DIR/spec.md"
+```
+
+Write the plan to `$FEATURE_DIR/plan.md` (same format as `.claude/plan.md`).
+Also write a summary entry to `.claude/plan.md` linking to the feature:
+```markdown
+## Feature: {N}-{slug}
+Files: .claude/features/{N}-{slug}/plan.md
+Status: pending
+```
+
+This keeps the global plan.md as the tracker while feature details live in their own directory.
+Each feature directory is self-contained: `spec.md` + `plan.md` + any generated artifacts.
+
+**When NOT to use feature mode:** quick fixes, single-file changes, copilot mode (uses global plan.md).
+
+---
+
 ## Copilot Mode — Structured plan.md Output
 
 When running inside `/copilot` (detected by: `.claude/copilot-intent.md` exists):

package/templates/commands/clarify.md

@@ -0,0 +1,160 @@
+---
+name: clarify
+description: >
+  Resolve ambiguity in a feature request, spec, milestone, or task BEFORE any planning or coding.
+  Triggers on: "clarify this", "what do you mean by", "I'm not sure what to build", "vague spec",
+  "clarify the requirements", "before we plan", "let's get clear on", "help me define",
+  "what exactly should it do", "I need to think through", "unclear requirements",
+  "what are the acceptance criteria", "define the scope", "what's in scope", "what's out of scope",
+  "who is this for", "what does done look like", "edge cases for", "what should happen when",
+  "clarify before building", "let's clarify before we start".
+  NOT triggered by: "add X", "implement X", "build X" alone — those go to /add directly.
+argument-hint: "[feature description, milestone text, or spec to clarify]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# /clarify — Resolve Before Planning
+
+$ARGUMENTS
+
+**EnterPlanMode** — read and think only. No file modifications.
+
+---
+
+## Purpose
+
+Clarification runs BEFORE /blueprint and BEFORE /spec.
+A vague input into /blueprint produces a vague plan. A vague plan produces wrong code.
+This command produces a `.claude/specs/{slug}.md` with unambiguous, testable requirements.
+
+---
+
+## Step 1: Parse Input
+
+If $ARGUMENTS is a milestone from plan.md → read `.claude/plan.md` to find it.
+If $ARGUMENTS is a feature description → use it directly.
+If $ARGUMENTS is blank → use **AskUserQuestion**: "What should I help clarify?"
+
+Extract from the input:
+- The goal (what problem this solves, for whom)
+- Anything already specified (concrete details)
+- Anything ambiguous or missing
+
+---
+
+## Step 2: Project Context
+
+Read existing context to ask informed questions:
+
+```bash
+# Stack and domain
+grep -i "domain:\|stack:\|scale:" CLAUDE.md 2>/dev/null | head -5
+
+# Existing patterns similar to this feature
+grep -ri "$ARGUMENTS" --include="*.ts" --include="*.py" --include="*.js" -l 2>/dev/null | head -5
+
+# Current constitution (if exists)
+cat .claude/constitution.md 2>/dev/null | head -20
+```
+
+---
+
+## Step 3: Structured Interrogation
+
+Ask ONLY the questions that are genuinely unresolved — maximum 5 questions at once.
+
+Use **AskUserQuestion** with these categories (skip any already answered in $ARGUMENTS):
+
+**Goal**
+- What problem does this solve? Who experiences it?
+- What does success look like from the user's perspective?
+
+**Scope boundary**
+- What is explicitly OUT of scope for this version?
+- What's the minimal version that still solves the problem?
+
+**Acceptance criteria**
+- How will we know it's done? (list 2-3 concrete, testable criteria)
+- What does a passing state look like vs. a failing state?
+
+**Failure modes**
+- What's the worst thing that could go wrong?
+- What should happen when X fails? (fill in X from the feature)
+
+**Constraints**
+- Any performance, security, or backwards-compatibility requirements?
+- Any existing code this must integrate with?
+
+Do NOT ask about implementation details — only about behavior and requirements.
+
+---
+
+## Step 4: Write the Clarified Spec
+
+After answers received, generate a slug from $ARGUMENTS:
+```bash
+SLUG=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-40)
+mkdir -p .claude/specs
+```
+
+Write `.claude/specs/${SLUG}.md`:
+
+```markdown
+# Spec: {feature title}
+clarified: {today's date}
+status: ready-for-blueprint
+
+## Goal
+{who uses this and what problem it solves — 1-2 sentences}
+
+## User Stories
+- As a {user type}, I want to {action} so that {outcome}
+- As a {user type}, I want to {action} so that {outcome}
+
+## Acceptance Criteria
+1. {concrete, testable — "given X, when Y, then Z" format}
+2. {concrete, testable}
+3. {concrete, testable}
+
+## Out of Scope
+- {explicitly excluded item}
+- {explicitly excluded item}
+
+## Failure Modes
+- {what happens when X fails — expected behavior}
+- {what happens when Y fails — expected behavior}
+
+## Constraints
+- {performance / security / compatibility requirement, or "none"}
+
+## Open Questions
+- {any remaining unknowns — low priority, answer before implementation if possible}
+```
+
+---
+
+## Step 5: Next Step
+
+**ExitPlanMode**
+
+Output:
+```
+Spec written: .claude/specs/{slug}.md
+Acceptance criteria: N
+Open questions: N (or "none")
+
+Next: /blueprint .claude/specs/{slug}.md
+```
+
+If open questions remain → ask user to resolve them before /blueprint.
+If no open questions → declare spec ready.
+
+---
+
+## Completion Rule
+
+Show: the spec file path.
+Show: acceptance criteria count.
+Show: any open questions.
+Do not write any code during /clarify — ever.

package/templates/commands/constitute.md

@@ -0,0 +1,190 @@
+---
+name: constitute
+description: >
+  Write or update the project constitution — explicit ground rules that govern all AI behavior.
+  Distinct from CLAUDE.md (operational config). The constitution is human-authored governance.
+  Triggers on: "write a constitution", "set ground rules", "define project rules",
+  "what are the non-negotiables", "project principles", "project constraints",
+  "what should Claude never do", "define the definition of done", "coding standards",
+  "project-level rules", "forbidden patterns", "required patterns",
+  "project constitution", "set constraints", "governance rules",
+  "architectural principles", "project norms", "what are our standards",
+  "define our conventions", "constitution for this project", "write the rules".
+argument-hint: "[blank to create interactively, or path to existing constitution to update]"
+disable-model-invocation: true
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# /constitute — Write the Project Constitution
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+The constitution is the highest-priority governance document in a project.
+It is written by the **human**, not generated from code.
+Every /add, /fix, /blueprint, and /copilot milestone checks it before implementing.
+
+**Hierarchy:**
+```
+constitution.md  ← human governance (this command)
+CLAUDE.md        ← operational config (/setup)
+plan.md          ← current work (/blueprint)
+```
+
+---
+
+## Step 1: Check Existing State
+
+```bash
+# Check if constitution already exists
+cat .claude/constitution.md 2>/dev/null | head -40
+
+# Read CLAUDE.md for current project identity
+grep -i "domain:\|stack:\|scale:\|priority" CLAUDE.md 2>/dev/null | head -10
+```
+
+If constitution exists → present it and ask: "Update existing, or rewrite from scratch?"
+If creating new → proceed to Step 2.
+
+---
+
+## Step 2: Guided Constitution Interview
+
+Use **AskUserQuestion** — one group at a time. Do NOT ask all at once.
+
+**Group 1: Non-negotiables**
+- What must NEVER be done in this codebase? (e.g., no direct DB writes from controllers, no hardcoded credentials, no breaking API changes without versioning)
+- What external libraries / frameworks are forbidden?
+
+**Group 2: Required patterns**
+- What patterns MUST always be used? (e.g., all state changes through events, all errors logged before thrown, all public APIs documented)
+- What conventions are load-bearing? (change them and everything breaks)
+
+**Group 3: Definition of Done**
+- What does "done" mean for this project? (tests pass? PR review? deployed? docs updated?)
+- What quality gates must every change pass?
+
+**Group 4: Architectural commitments**
+- What architectural decisions are already settled and not open for debate? (e.g., "we use PostgreSQL, not MongoDB", "all services are REST, not GraphQL")
+- What is the source of truth for data? For auth? For state?
+
+**Group 5: Scope and values**
+- Who are the users and what do they value most? (performance? simplicity? reliability?)
+- What should be optimized for when priorities conflict?
+
+---
+
+## Step 3: Write the Constitution
+
+Write `.claude/constitution.md`:
+
+```markdown
+# Project Constitution
+project: {project name from CLAUDE.md}
+created: {today's date}
+last_updated: {today's date}
+version: 1
+
+---
+
+## Non-Negotiables (Never Do This)
+
+These rules are inviolable. No exception, no matter the deadline or pressure.
+
+- {rule — specific and verifiable}
+- {rule — specific and verifiable}
+- {rule — specific and verifiable}
+
+## Required Patterns (Always Do This)
+
+These patterns must be used in all new code. Deviations require explicit approval.
+
+- {pattern — specific and verifiable}
+- {pattern — specific and verifiable}
+
+## Forbidden Dependencies
+
+Libraries, frameworks, or services that must never be introduced:
+
+- {dependency — with reason}
+
+## Architectural Commitments
+
+Decisions already made. Not open for debate without a /debate session.
+
+| Concern | Decision | Reason |
+|---------|----------|--------|
+| Database | {choice} | {reason} |
+| Auth | {choice} | {reason} |
+| API style | {choice} | {reason} |
+| {other} | {choice} | {reason} |
+
+## Definition of Done
+
+A change is only "done" when ALL of the following are true:
+
+- [ ] {criterion — e.g., "tests pass (npm test exits 0)"}
+- [ ] {criterion — e.g., "PR review approved"}
+- [ ] {criterion — e.g., "no new lint warnings"}
+- [ ] {criterion — e.g., "relevant docs updated"}
+
+## Priority Hierarchy
+
+When requirements conflict, resolve in this order:
+
+1. {highest priority — e.g., "Data integrity over performance"}
+2. {second priority}
+3. {third priority}
+
+## User Values
+
+Users of this project value (in order): {e.g., "reliability > speed > features"}
+Optimise in this order when trade-offs arise.
+
+---
+
+_This constitution governs all AI actions in this project.
+Any command (/add, /fix, /copilot) must check this file before implementing._
+```
+
+---
+
+## Step 4: Wire It Into the Workflow
+
+After writing, update CLAUDE.md to reference the constitution:
+
+```bash
+grep -q "constitution" CLAUDE.md && echo "already referenced" || echo "needs wiring"
+```
+
+If not referenced → add to CLAUDE.md Rules section:
+```
+## Rules
+...
+N. **Constitution** — Read `.claude/constitution.md` before any implementation. Non-negotiables override all other instructions.
+```
+
+---
+
+## Completion Rule
+
+Show:
+1. Constitution file path: `.claude/constitution.md`
+2. Count of non-negotiables
+3. Count of required patterns
+4. Definition of done criteria count
+5. Whether CLAUDE.md was updated
+
+Output:
+```
+Constitution written: .claude/constitution.md
+Non-negotiables: N rules
+Required patterns: N rules
+Definition of done: N criteria
+CLAUDE.md: updated / already referenced
+
+Every /add, /fix, and /copilot milestone will now check this file.
+```

package/templates/commands/copilot.md

@@ -49,17 +49,33 @@ Read these files (skip any that don't exist):
 
 ---
 
+## Step 1b: Governance Check
+
+```bash
+[ -f .claude/constitution.md ] && echo "constitution=found" || echo "constitution=missing"
+ls .claude/specs/*.md 2>/dev/null | head -5
+```
+
+If constitution missing → note in goals.md: "No constitution — run /constitute to define project rules"
+(Do NOT block execution — constitution is recommended, not required)
+
+---
+
 ## Step 2: Decide What To Do
 
 Follow this decision tree in order:
 
 1. **No CLAUDE.md filled?** → Run `/setup` with the intent from copilot-intent.md
-2. **No plan.md?** → Run `/blueprint` to generate a milestone plan
-3. **Plan has incomplete milestones?** → Find the next one (respecting dependencies), implement it
-4. **3 milestones done since last /evolve?** → Run `/evolve` first, then continue
-5. **All milestones done?** → Run `/audit` on the full project
-6. **Review passes?** → Run `/ship` and deploy
-7. **Deploy succeeds?** → Write `COPILOT_COMPLETE` to goals.md, generate copilot-report.md
+2. **No plan.md but specs exist?** → Run `/blueprint .claude/specs/{latest-spec}` to derive plan from spec
+3. **No plan.md, no specs?** → Run `/blueprint` to generate a milestone plan from intent
+4. **Plan has incomplete milestones?** → Find the next one (respecting dependencies):
+   - If `constitution.md` exists → spawn `constitution-guard` agent with milestone details before implementing
+   - If constitution-guard returns VIOLATION → log to `blockers.md`, skip this milestone, continue to next
+   - If APPROVED (or no constitution) → implement the milestone
+5. **3 milestones done since last /evolve?** → Run `/evolve` first, then continue
+6. **All milestones done?** → Run `/analyze` then `/audit` on the full project
+7. **Review passes?** → Run `/ship` and deploy
+8. **Deploy succeeds?** → Write `COPILOT_COMPLETE` to goals.md, generate copilot-report.md
 
 ---
 
@@ -92,18 +108,24 @@ For each milestone in plan.md:
 After every 3 completed milestones:
 1. Run `/reflexes analyze` — detect patterns from tool-use observations, create/update reflexes
 2. Run `/evolve` — scans git history for patterns, creates agents if evidence found
-3. Check if CLAUDE.md conventions need updating
-4. Re-read plan.md — re-evaluate remaining milestone priorities
-5. If a blocked milestone can now be unblocked (new agents/context available) → retry it
+3. Run `/analyze` — check for GHOST milestones (marked done but not implemented) and spec→plan drift
+   - If GHOST milestones found → set their status back to `pending` in plan.md, add back to queue
+   - If spec drift found → log gap to `.claude/memory/blockers.md` as a fix milestone
+4. Check if CLAUDE.md conventions need updating
+5. Re-read plan.md — re-evaluate remaining milestone priorities
+6. If a blocked milestone can now be unblocked (new agents/context available) → retry it
 
 ---
 
 ## Step 5: Final Review
 
 When all milestones show status `done` (or `blocked` with no unblock path):
-1. Run `/audit` on the full project against copilot-intent.md
-2. If review finds gaps → create fix milestones, add to plan.md, continue building
-3. If review passes → proceed to ship
+1. Run `/analyze` — verify all done milestones are actually implemented (no GHOSTs)
+   - If GHOST milestones found → re-open them, add as fix milestones, continue building
+   - If /analyze shows consistency ≥ 90% → proceed
+2. Run `/audit` on the full project against copilot-intent.md
+3. If review finds gaps → create fix milestones, add to plan.md, continue building
+4. If review passes → proceed to ship
 
 ---
 

package/templates/commands/dream.md

@@ -126,12 +126,43 @@ All ✓ required before printing "project ready."
 
 ---
 
+## Phase 5: Spec-Driven Readiness
+
+After quality gate passes, check and suggest the spec-driven workflow:
+
+```bash
+[ -f .claude/constitution.md ] && echo "constitution=found" || echo "constitution=missing"
+ls .claude/specs/*.md 2>/dev/null | head -3
+```
+
+Always output this next-steps block:
+
+```
+─── Spec-Driven Workflow: Next Steps ────────────────────
+  1. /constitute          — define project ground rules (non-negotiables, required patterns,
+                            definition of done). Copilot checks this before every milestone.
+
+  2. /spec [feature]      — write a structured spec for your first feature.
+                            Produces: user stories + acceptance criteria + out-of-scope.
+                            Feeds directly into /blueprint for a better plan.
+
+  3. /clarify [spec]      — resolve any open questions in the spec before planning.
+
+  4. /blueprint [spec]    — derive a milestone plan from the spec.
+                            spec-reviewer validates quality before planning starts.
+
+  5. /copilot             — autonomous execution: spec → plan → build → test → ship.
+─────────────────────────────────────────────────────────
+```
+
+---
+
 ## Completion Rule
 
 Show:
 1. The created `CLAUDE.md` (full content)
 2. The created `goals.md` (full content)
 3. The level checklist (what was built)
-4. First task to work on
+4. The spec-driven next steps block (always — even for existing projects)
 
 Do not say "project ready" without showing these four outputs.

package/templates/commands/evolve.md

@@ -90,7 +90,7 @@ If PLAN is empty: skip to Cycle 2.
 
 ---
 
-## Cycle 2: Knowledge Consolidation (if sessions ≥ 3 since last consolidation)
+## Cycle 2: Knowledge Consolidation (if sessions ≥ 2 since last consolidation)
 
 Read `capabilities/evolution/cycle2-knowledge.md` and run.
 Outputs: consolidated patterns, pruned stale memory, enriched knowledge-index
@@ -225,6 +225,28 @@ This closes the loop: /evolve creates capability → orchestrator immediately re
 
 ---
 
+## Step 7f: Spec and Plan Drift Analysis
+
+After generating/updating skills and agents, check for documentation drift:
+
+```bash
+ls .claude/plan.md .claude/specs/*.md 2>/dev/null
+```
+
+If plan.md exists → run `/analyze plan`:
+- Identifies GHOST milestones (marked done but files missing)
+- Surfaces dependency violations
+
+Append drift findings to `ops/evolution-log.md`:
+```
+| {date} | DRIFT | {N ghost milestones} | {N unplanned capabilities} | {1-line summary} |
+```
+
+If GHOST milestones found → set their status back to `pending` in plan.md.
+This closes a common drift loop: code gets deleted or renamed, plan.md still says done.
+
+---
+
 ## Step 8: Promote GENERAL Skills
 
 For any fix tagged GENERAL in EVALUATE:

package/templates/commands/fix.md

@@ -14,6 +14,18 @@ Load: shared/tdd.md + shared/completion-rule.md before starting.
 
 ---
 
+## Pre-Flight: Constitution Check
+
+```bash
+[ -f .claude/constitution.md ] && echo "constitution=found" || echo "no constitution"
+```
+
+If found: read `## Non-Negotiables` before fixing.
+The fix must not violate a non-negotiable — a "fix" that breaks a project rule is not a fix.
+Flag any conflict explicitly before proceeding to Phase 1.
+
+---
+
 ## Pre-Flight Analysis (intelligent-dispatch)
 
 Load `shared/intelligent-dispatch.md`.