azclaude-copilot 0.4.12 → 0.4.13

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

@@ -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`.

package/templates/commands/issues.md

@@ -0,0 +1,168 @@
+---
+name: issues
+description: >
+  Convert plan.md milestones to GitHub Issues, making copilot progress visible to the whole team.
+  Triggers on: "create issues", "push to GitHub issues", "create GitHub issues",
+  "open issues from plan", "sync to issues", "milestones to issues",
+  "make issues from plan", "track in GitHub", "create tickets", "push plan to issues",
+  "open tickets", "create GitHub tickets", "sync plan with issues",
+  "open issues for each milestone", "team visibility", "issue tracker",
+  "track progress in GitHub", "post to issues", "push milestones to GitHub",
+  "issues from milestones", "create an issue for each task".
+  Requires: gh CLI authenticated. Reads: .claude/plan.md.
+argument-hint: "[blank for all pending milestones, or 'M{N}' for a specific milestone]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# /issues — Convert Plan to GitHub Issues
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+After /blueprint produces plan.md, this command pushes each pending milestone
+to GitHub as an issue — giving the team visibility into what copilot is building,
+and creating a traceable link between plan and code.
+
+When a milestone completes in /copilot, close the corresponding issue with the commit SHA.
+
+---
+
+## Step 1: Pre-Flight Checks
+
+```bash
+# Verify gh CLI is available and authenticated
+gh auth status 2>&1 | head -3
+
+# Verify we're in a git repo with a remote
+git remote get-url origin 2>/dev/null
+
+# Verify plan.md exists
+ls .claude/plan.md 2>/dev/null && echo "plan found" || echo "no plan — run /blueprint first"
+```
+
+If `gh` not found → output:
+```
+gh CLI not found. Install with: https://cli.github.com/
+Then authenticate: gh auth login
+```
+Stop.
+
+If no plan.md → output:
+```
+No plan.md found. Run /blueprint first to create a structured plan.
+```
+Stop.
+
+---
+
+## Step 2: Extract Milestones
+
+Read `.claude/plan.md`. Parse each milestone:
+- ID (M1, M2, …)
+- Title
+- Status (`pending`, `in-progress`, `done`, `blocked`)
+- Description / files / commit fields
+- `Depends:` field
+
+If $ARGUMENTS = `M{N}` → process only that milestone.
+If $ARGUMENTS = blank → process all `pending` and `in-progress` milestones.
+Skip `done` milestones (already shipped).
+
+---
+
+## Step 3: Check for Existing Issues
+
+```bash
+# Check if issues already exist for this plan
+gh issue list --label "azclaude" --limit 50 --json number,title 2>/dev/null
+```
+
+For each milestone, check if an issue with the same title already exists.
+If found → skip creation (do not duplicate), note the existing issue number.
+
+---
+
+## Step 4: Create Issues
+
+For each milestone to process (not already an issue):
+
+```bash
+gh issue create \
+  --title "M{N}: {milestone title}" \
+  --body "$(cat <<'BODY'
+## Milestone M{N}
+
+{milestone description from plan.md}
+
+### Files Expected
+{Files: field from milestone}
+
+### Depends On
+{Depends: field, or "none"}
+
+### Commit Format
+{Commit: field from milestone}
+
+---
+_Generated by azclaude /issues from .claude/plan.md_
+_Track progress: this issue closes when the milestone is committed._
+BODY
+)" \
+  --label "azclaude" \
+  --label "copilot-milestone"
+```
+
+Store the returned issue URL.
+
+---
+
+## Step 5: Write Issue Links to plan.md
+
+After creating issues, append issue numbers back to plan.md milestones:
+
+For each milestone that now has a GitHub issue, add:
+```
+Issue: #{number}  https://github.com/{owner}/{repo}/issues/{number}
+```
+
+This creates the plan→issue traceability link.
+
+---
+
+## Step 6: Create Labels (if missing)
+
+```bash
+# Create labels if they don't exist yet
+gh label create "azclaude" --color "0075ca" --description "Managed by azclaude copilot" 2>/dev/null || true
+gh label create "copilot-milestone" --color "7057ff" --description "azclaude plan milestone" 2>/dev/null || true
+```
+
+---
+
+## Completion Rule
+
+Show:
+```
+GitHub Issues Created
+═════════════════════
+Repository: {owner/repo}
+
+  #N  M1: {title}  → {url}
+  #N  M2: {title}  → {url}
+  ...
+
+Skipped (already done): {count}
+Skipped (already had issue): {count}
+
+plan.md updated with issue links.
+
+Team members can now track progress at:
+  https://github.com/{owner}/{repo}/issues?label=azclaude
+```
+
+Do not create issues for `done` milestones.
+Do not delete or close existing issues during /issues.