create-sdd-project 0.15.0 → 0.16.0

package/README.md

@@ -338,7 +338,7 @@ Cross-model reviews only trigger when at least one external CLI is available (Ge
 - **Standard** (features): 0 → 1 → 2 → 3 → 4 → 5 (+QA) → 6
 - **Complex** (architectural changes): 0 → 1 (+ADR) → 2 → 3 → 4 → 5 (+QA) → 6
 
-### 4 Autonomy Levels
+### 5 Autonomy Levels
 
 | Level | Name | Human Checkpoints | Best For |
 |-------|------|-------------------|----------|
@@ -346,6 +346,7 @@ Cross-model reviews only trigger when at least one external CLI is available (Ge
 | L2 | Trusted | Plan + Merge | Normal development **(default)** |
 | L3 | Autopilot | Merge only | Well-defined, repetitive tasks |
 | L4 | Full Auto | None (CI/CD gates only) | Bulk simple tasks |
+| L5 | PM Autonomous | None + auto feature sequencing | Multi-feature batch execution via `start pm` |
 
 Quality gates (tests, lint, build, validators) **always run** regardless of level.
 
@@ -434,7 +435,7 @@ project/
 │
 ├── .gemini/
 │   ├── agents/                          # 10 agents (Gemini format)
-│   ├── skills/                          # Same 4 skills
+│   ├── skills/                          # Same 5 skills
 │   ├── commands/                        # Slash commands (workflow + review + context + project review)
 │   └── settings.json                    # Gemini configuration
 │

package/lib/config.js

@@ -82,6 +82,7 @@ const AUTONOMY_LEVELS = [
   { level: 2, name: 'Trusted', desc: 'Human reviews plans + merges only (normal development)', default: true },
   { level: 3, name: 'Autopilot', desc: 'Human only approves merges (well-defined, repetitive tasks)' },
   { level: 4, name: 'Full Auto', desc: 'No human checkpoints, CI/CD gates only (bulk simple tasks)' },
+  { level: 5, name: 'PM Autonomous', desc: 'PM Agent orchestrates features end-to-end (requires "start pm" to activate)' },
 ];
 
 const BRANCHING_STRATEGIES = [

package/lib/diff-generator.js

@@ -83,7 +83,7 @@ function runInitDiffReport(config) {
   if (aiTools !== 'gemini') {
     const claudeSkills = countFiles(path.join(templateDir, '.claude', 'skills'));
     wouldCreate.push(`  .claude/agents/             ${agentCount} agents${removedAgents > 0 ? ` (${removedAgents} removed: ${projectType}-only)` : ''}`);
-    wouldCreate.push(`  .claude/skills/             ${claudeSkills} files (4 skills)`);
+    wouldCreate.push(`  .claude/skills/             ${claudeSkills} files (5 skills)`);
     wouldCreate.push('  .claude/hooks/              quick-scan.sh');
     wouldCreate.push('  .claude/settings.json');
     wouldCreate.push('  .claude/commands/           .gitkeep');
@@ -93,7 +93,7 @@ function runInitDiffReport(config) {
     const geminiSkills = countFiles(path.join(templateDir, '.gemini', 'skills'));
     const geminiCmds = countFiles(path.join(templateDir, '.gemini', 'commands'));
     wouldCreate.push(`  .gemini/agents/             ${agentCount} agents${removedAgents > 0 ? ` (${removedAgents} removed: ${projectType}-only)` : ''}`);
-    wouldCreate.push(`  .gemini/skills/             ${geminiSkills} files (4 skills)`);
+    wouldCreate.push(`  .gemini/skills/             ${geminiSkills} files (5 skills)`);
     wouldCreate.push(`  .gemini/commands/           ${geminiCmds} commands`);
     wouldCreate.push('  .gemini/styles/             default.md');
     wouldCreate.push('  .gemini/settings.json');
@@ -163,14 +163,14 @@ function runUpgradeDiffReport(config, state) {
   if (aiTools !== 'gemini') {
     const agentCount = countAgents(projectType);
     replaceItems.push(`.claude/agents/             ${agentCount} agents`);
-    replaceItems.push('.claude/skills/             4 skills');
+    replaceItems.push('.claude/skills/             5 skills');
     replaceItems.push('.claude/hooks/              quick-scan.sh');
     replaceItems.push('.claude/settings.json       hooks updated, permissions preserved');
   }
   if (aiTools !== 'claude') {
     const agentCount = countAgents(projectType);
     replaceItems.push(`.gemini/agents/             ${agentCount} agents`);
-    replaceItems.push('.gemini/skills/             4 skills');
+    replaceItems.push('.gemini/skills/             5 skills');
     replaceItems.push('.gemini/commands/           TOML commands');
     replaceItems.push('.gemini/styles/             default.md');
     replaceItems.push('.gemini/settings.json');

package/lib/doctor.js

@@ -13,6 +13,7 @@ const {
   getPackageVersion,
   detectAiTools,
   detectProjectType,
+  readAutonomyLevel,
 } = require('./upgrade-generator');
 
 const PASS = 'pass';
@@ -66,6 +67,9 @@ function runDoctor(cwd) {
   // 10. Project Memory
   results.push(checkProjectMemory(cwd));
 
+  // 11. Autonomy/Skills Consistency
+  results.push(checkAutonomySkillConsistency(cwd, aiTools));
+
   return results;
 }
 
@@ -486,6 +490,45 @@ function checkProjectMemory(cwd) {
   };
 }
 
+function checkAutonomySkillConsistency(cwd, aiTools) {
+  const { level } = readAutonomyLevel(cwd);
+
+  if (level < 5) {
+    return {
+      status: PASS,
+      message: 'Autonomy/skills consistency: OK',
+      details: [],
+    };
+  }
+
+  // L5 set — verify pm-orchestrator skill exists in all configured tools
+  const toolDirs = [];
+  if (aiTools !== 'gemini') toolDirs.push('.claude');
+  if (aiTools !== 'claude') toolDirs.push('.gemini');
+
+  const missing = [];
+  for (const dir of toolDirs) {
+    const pmSkillPath = path.join(cwd, dir, 'skills', 'pm-orchestrator', 'SKILL.md');
+    if (!fs.existsSync(pmSkillPath)) {
+      missing.push(`${dir}/skills/pm-orchestrator/SKILL.md`);
+    }
+  }
+
+  if (missing.length > 0) {
+    return {
+      status: WARN,
+      message: 'L5 (PM Autonomous) set but pm-orchestrator skill missing',
+      details: [...missing.map((f) => `Missing: ${f}`), 'Run: npx create-sdd-project --upgrade'],
+    };
+  }
+
+  return {
+    status: PASS,
+    message: 'Autonomy/skills consistency: L5 + pm-orchestrator present',
+    details: [],
+  };
+}
+
 module.exports = {
   runDoctor,
   printResults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"

package/template/.claude/settings.json

@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '{\"additionalContext\": \"Context was compacted. BEFORE doing anything else: (1) Read the product tracker Active Session (docs/project_notes/product-tracker.md) for context recovery. (2) Re-read the SKILL.md for your current workflow (.claude/skills/development-workflow/SKILL.md) to know what actions are required at your current step. (3) If at Step 5 or later, you MUST read references/merge-checklist.md and fill the Merge Checklist Evidence table in the ticket before requesting merge approval.\"}'",
+            "command": "bash -c 'if [ -f \"$CLAUDE_PROJECT_DIR/docs/project_notes/pm-session.lock\" ]; then echo \"{\\\"additionalContext\\\": \\\"PM Autonomous session active. BEFORE doing anything else: (1) Read docs/project_notes/pm-session.md for full PM state. (2) Read the product tracker Active Session. (3) Run: continue pm\\\"}\"; else echo \"{\\\"additionalContext\\\": \\\"Context was compacted. BEFORE doing anything else: (1) Read the product tracker Active Session (docs/project_notes/product-tracker.md) for context recovery. (2) Re-read the SKILL.md for your current workflow (.claude/skills/development-workflow/SKILL.md) to know what actions are required at your current step. (3) If at Step 5 or later, you MUST read references/merge-checklist.md and fill the Merge Checklist Evidence table in the ticket before requesting merge approval.\\\"}\"; fi'",
             "statusMessage": "Injecting recovery context..."
           }
         ]

package/template/.claude/skills/development-workflow/SKILL.md

@@ -39,17 +39,19 @@ description: "Orchestrates the complete development workflow for each feature. I
 
 Read the **Autonomy Level** from `CLAUDE.md` section 2.
 
-| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto |
-|------------|:-:|:-:|:-:|:-:|
-| Spec Approval (Step 0) | Required | Auto | Auto | Auto |
-| Ticket Approval (Step 1) | Required | Auto | Auto | Auto |
-| Plan Approval (Step 2) | Required | Required | Auto | Auto |
-| Commit Approval (Step 4) | Required | Auto | Auto | Auto |
-| Merge Approval (Step 5) | Required | Required | Required | Auto |
+| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto | L5 PM Auto |
+|------------|:-:|:-:|:-:|:-:|:-:|
+| Spec Approval (Step 0) | Required | Auto | Auto | Auto | Auto |
+| Ticket Approval (Step 1) | Required | Auto | Auto | Auto | Auto |
+| Plan Approval (Step 2) | Required | Required | Auto | Auto | Auto |
+| Commit Approval (Step 4) | Required | Auto | Auto | Auto | Auto |
+| Merge Approval (Step 5) | Required | Required | Required | Auto | Auto |
+| Next Feature (PM loop) | — | — | — | — | Auto |
 
 - **Auto** = proceed without asking; log in product tracker → "Auto-Approved Decisions" table
 - **Required** = ask user explicitly; do NOT continue without approval
 - **Quality gates always run** regardless of level (tests, lint, build, validators)
+- **L5** behaves like L4 for individual checkpoints. The `pm-orchestrator` skill handles automatic feature sequencing via `start pm`.
 - **Steps are strictly sequential.** Do NOT start a later step before the current checkpoint is approved — even when the checkpoint is Auto (auto-approval still happens in order, not in parallel). In particular, do NOT generate the Implementation Plan (Step 2) while Spec Approval (Step 0) is still pending. Reason: if the spec review finds issues, any plan built on the flawed spec must be discarded and redone — parallelizing wastes work and risks shipping a plan that doesn't match the final spec.
 
 ---

package/template/.claude/skills/development-workflow/references/complexity-guide.md

@@ -77,6 +77,7 @@ Complexity and Autonomy Level combine to determine the effective workflow overhe
 | Standard + L3-4 | Fast execution, quality gates + QA still enforced |
 | Complex + L1 | Full ceremony (all checkpoints + QA + ADR) |
 | Complex + L3-4 | Fast but with QA engineer + ADR |
+| Any + L5 | Same as L4 per feature, but PM Orchestrator auto-sequences features via `start pm` |
 
 **Note:** The user can override the autonomy level per-task. E.g., "use level 1 for this task" forces all checkpoints regardless of the project-level setting.
 

package/template/.claude/skills/pm-orchestrator/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: pm-orchestrator
+description: "PM Agent that orchestrates sequential multi-feature development. Invoke with: 'start pm', 'continue pm', 'stop pm', or 'pm status'."
+---
+
+# PM Orchestrator
+
+Autonomously develops multiple features in sequence using the `development-workflow` skill. Requires **L5 (PM Autonomous)** autonomy level.
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `start pm` | Start a new autonomous session — classify batch, then loop |
+| `continue pm` | Resume after /compact or session restart |
+| `stop pm` | Graceful stop after current feature completes |
+| `pm status` | Show progress summary from pm-session.md |
+
+## Prerequisites
+
+Before starting:
+
+1. **Autonomy Level must be L5.** Read `CLAUDE.md` → verify `Autonomy Level: 5 (PM Autonomous)`. If not L5, tell the user and stop.
+2. **Product tracker must have pending features.** Read `docs/project_notes/product-tracker.md` → Features table. If no features have step < 6/6, there is nothing to do.
+3. **Working tree must be clean.** Run `git status`. If dirty, ask user to commit or stash.
+4. **No active PM session.** Check if `docs/project_notes/pm-session.lock` exists. If it does, another PM session may be running — ask user before proceeding.
+
+---
+
+## `start pm` — New Autonomous Session
+
+### Phase 1: Batch Selection
+
+1. Read `docs/project_notes/product-tracker.md` → collect all features with step < 6/6.
+2. **Filter out** features whose dependencies are not yet done (check the Dependencies column and verify the dependency feature has step 6/6).
+3. **Sort** by priority (High > Medium > Low), then by feature ID ascending.
+4. Present the first **1-3 eligible features** to the user as a rolling batch:
+
+```
+PM Orchestrator — Batch Classification
+
+These features are ready to develop:
+
+| # | Feature | Type | Priority | Dependencies |
+|---|---------|------|----------|--------------|
+| 1 | F014 — Short Name | backend | High | F006 (done) |
+| 2 | F015 — Short Name | backend | Medium | none |
+| 3 | F016 — Short Name | fullstack | Medium | F014 |
+
+Classify complexity for each (Simple / Standard / Complex):
+```
+
+5. Wait for user to classify all features in the batch.
+
+### Phase 2: Session Initialization
+
+1. Create `docs/project_notes/pm-session.lock` with content: `session started at {ISO date}`.
+2. Create `docs/project_notes/pm-session.md` from `references/pm-session-template.md`:
+   - Fill **Started** date, **Session ID** (short random ID), **Target Branch** (from `docs/project_notes/key_facts.md` → branching strategy: github-flow → `main`, gitflow → `develop`).
+   - Fill the **Current Batch** table with classified features.
+   - Set **Status** to `in-progress`.
+
+### Phase 3: Orchestration Loop
+
+For each feature in the batch:
+
+#### a. Pre-flight Checks
+
+- **Kill switch**: If `docs/project_notes/pm-stop.md` exists → stop gracefully (go to Shutdown).
+- **Lock**: If `docs/project_notes/pm-session.lock` is missing → stop (session was terminated externally).
+- **Circuit breaker**: If 3 consecutive features are `blocked` → stop and report to user.
+- **Clean workspace**: Run `git status`. If dirty, commit or stash before proceeding.
+
+#### b. Start Feature
+
+1. Update `pm-session.md`: set current feature status to `in-progress`, note step 0/6.
+2. Invoke the `development-workflow` skill:
+   - Command: `start task FXXX as [Simple|Standard|Complex]`
+   - The development-workflow reads L5 → all checkpoints auto-approve.
+   - All quality gates run as normal (tests, lint, build, validators, code review, QA).
+   - At Step 5 (Review): execute `/audit-merge` before the merge checklist evidence.
+
+#### c. Feature Completed (Step 6 done)
+
+1. Verify `docs/project_notes/product-tracker.md` shows the feature at step 6/6 with status `done`.
+2. **Post-merge sanity check**: Run `npm test` (or the project's test command) on the target branch.
+   - If tests **fail** → STOP immediately. The merged feature broke the target branch. Report to user.
+   - If tests **pass** → continue.
+3. Update `pm-session.md`: set feature status to `done`, record approximate duration.
+4. Reset consecutive failure counter to 0.
+
+#### d. Feature Failed
+
+If the development-workflow encounters a failure during any step:
+
+1. The existing retry/fix loop runs (max 3 retries per step, per the `failure-handling.md` reference).
+2. If retries exhausted:
+   - Update `pm-session.md`: set feature status to `blocked`, note the failure reason.
+   - Increment consecutive failure counter.
+   - Skip to the next feature in the batch.
+3. If merge conflicts prevent completion:
+   - Mark as `blocked` with reason "merge conflict".
+   - Skip to next feature.
+
+#### e. Batch Boundary
+
+After each completed or blocked feature:
+
+1. **Re-read** `docs/project_notes/product-tracker.md` to check for newly unblocked features (dynamic dependency resolution).
+2. If the current batch is exhausted and more eligible features remain:
+   - Present the next 1-3 features to the user for complexity classification.
+   - Add them to the batch in `pm-session.md`.
+3. If **3+ features completed** in this session → suggest the user run `/compact` before continuing (context may be getting heavy).
+4. If max session limit reached (**5 features**) → stop and report.
+
+### Phase 4: Shutdown
+
+1. Update `pm-session.md`:
+   - Set **Status** to `completed` (if all done) or `stopped` (if interrupted).
+   - Ensure all feature statuses are up to date.
+2. Remove `docs/project_notes/pm-session.lock`.
+3. Remove `docs/project_notes/pm-stop.md` if it exists.
+4. Print final report:
+
+```
+PM Session Complete
+
+| Feature | Status | Duration | Notes |
+|---------|--------|----------|-------|
+| F014 | done | ~8 min | Clean |
+| F015 | done | ~12 min | 1 QA fix |
+| F016 | blocked | — | Merge conflict |
+
+Completed: 2/3 | Blocked: 1/3 | Remaining: 0
+```
+
+---
+
+## `continue pm` — Resume After /compact or Restart
+
+1. Read `docs/project_notes/pm-session.md`. If it doesn't exist, inform user there is no active session.
+2. **Validate session Status.** If Status is `completed` or `stopped`, inform user the session has ended. To start a new one, delete pm-session.md and run `start pm`.
+3. **Re-create lock.** If `docs/project_notes/pm-session.lock` is missing (e.g., after terminal crash), re-create it with content: `session resumed at {ISO date}`.
+4. Find the feature with status `in-progress`:
+   - Read its ticket file and the product tracker Active Session to determine current step.
+   - Resume the `development-workflow` from that step.
+5. After the in-progress feature completes, re-enter the Orchestration Loop at step (e).
+6. If no `in-progress` feature exists but `pending` features remain, pick the next one and enter step (b).
+
+---
+
+## `stop pm` — Graceful Stop
+
+1. Create `docs/project_notes/pm-stop.md` with content: `stop requested at {ISO date}`.
+2. The orchestration loop will detect this file at the next pre-flight check and shut down gracefully.
+3. The current feature will complete its current step before stopping.
+
+---
+
+## `pm status` — Progress Summary
+
+1. Read `docs/project_notes/pm-session.md`.
+2. Display the Current Batch table and Recovery Instructions.
+3. If no session exists, inform the user.
+
+---
+
+## Guardrails
+
+| Guardrail | Value | Rationale |
+|-----------|-------|-----------|
+| Max features per session | 5 | Model attention degrades after many iterations |
+| Consecutive failure circuit breaker | 3 | Prevent wasting resources on a systemic issue |
+| Kill switch | `pm-stop.md` or `stop pm` | User can always halt the loop |
+| Session lock | `pm-session.lock` | Prevents concurrent PM sessions |
+| Quality gates | Always enforced | Tests, lint, build, validators, code review, QA, `/audit-merge` |
+| Post-merge sanity | `npm test` on target branch | Catch regressions immediately |
+| Rolling batch | 1-3 features | Avoid over-committing; allows dynamic re-prioritization |
+| Clean workspace | `git status` before each feature | Prevent dirty state contamination |
+
+## Edge Cases
+
+1. **Feature mid-execution during /compact**: `continue pm` reads pm-session.md → finds in-progress feature → reads tracker Active Session → resumes development-workflow from that step.
+
+2. **pm-session.md vs tracker disagreement**: Product tracker is the **source of truth**. If pm-session.md says "done" but tracker says "in-progress", trust the tracker and re-verify.
+
+3. **User modifies tracker mid-session**: PM re-reads tracker between features (not mid-feature). Changes take effect at the next feature boundary.
+
+4. **Branch already exists**: development-workflow Step 1 handles this — checks out existing branch and resumes.
+
+5. **L5 selected but `start task` used directly**: development-workflow at L5 behaves exactly like L4 (all checkpoints auto). The PM loop is opt-in via `start pm`, not forced by L5.
+
+6. **Batch classification changes**: User can `stop pm`, edit pm-session.md complexity column, then `continue pm`.
+
+7. **Post-merge sanity check fails**: STOP immediately. The merged feature introduced a regression on the target branch. Do NOT continue — user must investigate manually.
+
+8. **Gemini CLI limitations**: PM Orchestrator instructions are mirrored for Gemini. L5 PM Orchestrator is fully designed for Claude Code; Gemini support is best-effort.
+
+## References
+
+- `references/pm-session-template.md` — Template for the session state file
+- `.claude/skills/development-workflow/SKILL.md` — The workflow invoked for each feature
+- `docs/project_notes/product-tracker.md` — Source of truth for feature status
+- `.claude/skills/development-workflow/references/failure-handling.md` — Retry and rollback patterns
+
+## Constraints
+
+- **One feature at a time.** Sequential execution only — no parallel features.
+- **Do NOT skip quality gates.** Even at L5, tests/lint/build/validators/review/QA always execute.
+- **Do NOT force-resolve merge conflicts.** Mark as blocked and skip.
+- **Do NOT modify pm-session.md format.** Follow the template structure exactly.
+- **Do NOT continue after post-merge sanity failure.** Stop and report.

package/template/.claude/skills/pm-orchestrator/references/pm-session-template.md

@@ -0,0 +1,39 @@
+# PM Autonomous Session
+
+**Started:** {date}
+**Session ID:** {short-id}
+**Autonomy Level:** L5 (PM Autonomous)
+**Status:** in-progress
+**Target Branch:** {main|develop}
+
+## Current Batch
+
+| Feature | Complexity | Status | Duration | Notes |
+|---------|------------|--------|----------|-------|
+| F0XX | Simple | pending | — | — |
+
+## Completed Features
+
+_(Move features here as they complete)_
+
+| Feature | Complexity | Duration | Notes |
+|---------|------------|----------|-------|
+<!-- | F0XX | Simple | ~8 min | Clean | -->
+
+## Blocked Features
+
+_(Move features here if blocked)_
+
+| Feature | Reason | Step |
+|---------|--------|------|
+<!-- | F0XX | Merge conflict | 5/6 | -->
+
+## Recovery Instructions
+
+**Current feature:** (none yet)
+**Branch:** (none yet)
+**Next features:** (see Current Batch table)
+**Blocked:** (none)
+
+To resume after /compact: run `continue pm`
+To stop gracefully: run `stop pm`

package/template/.gemini/skills/development-workflow/SKILL.md

@@ -39,17 +39,19 @@ description: "Orchestrates the complete development workflow for each feature. I
 
 Read the **Autonomy Level** from `GEMINI.md`.
 
-| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto |
-|------------|:-:|:-:|:-:|:-:|
-| Spec Approval (Step 0) | Required | Auto | Auto | Auto |
-| Ticket Approval (Step 1) | Required | Auto | Auto | Auto |
-| Plan Approval (Step 2) | Required | Required | Auto | Auto |
-| Commit Approval (Step 4) | Required | Auto | Auto | Auto |
-| Merge Approval (Step 5) | Required | Required | Required | Auto |
+| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto | L5 PM Auto |
+|------------|:-:|:-:|:-:|:-:|:-:|
+| Spec Approval (Step 0) | Required | Auto | Auto | Auto | Auto |
+| Ticket Approval (Step 1) | Required | Auto | Auto | Auto | Auto |
+| Plan Approval (Step 2) | Required | Required | Auto | Auto | Auto |
+| Commit Approval (Step 4) | Required | Auto | Auto | Auto | Auto |
+| Merge Approval (Step 5) | Required | Required | Required | Auto | Auto |
+| Next Feature (PM loop) | — | — | — | — | Auto |
 
 - **Auto** = proceed without asking; log in product tracker → "Auto-Approved Decisions" table
 - **Required** = ask user explicitly; do NOT continue without approval
 - **Quality gates always run** regardless of level (tests, lint, build, validators)
+- **L5** behaves like L4 for individual checkpoints. The `pm-orchestrator` skill handles automatic feature sequencing via `start pm`.
 - **Steps are strictly sequential.** Do NOT start a later step before the current checkpoint is approved — even when the checkpoint is Auto (auto-approval still happens in order, not in parallel). In particular, do NOT generate the Implementation Plan (Step 2) while Spec Approval (Step 0) is still pending. Reason: if the spec review finds issues, any plan built on the flawed spec must be discarded and redone — parallelizing wastes work and risks shipping a plan that doesn't match the final spec.
 
 ---

package/template/.gemini/skills/development-workflow/references/complexity-guide.md

@@ -77,6 +77,7 @@ Complexity and Autonomy Level combine to determine the effective workflow overhe
 | Standard + L3-4 | Fast execution, quality gates + QA still enforced |
 | Complex + L1 | Full ceremony (all checkpoints + QA + ADR) |
 | Complex + L3-4 | Fast but with QA engineer + ADR |
+| Any + L5 | Same as L4 per feature, but PM Orchestrator auto-sequences features via `start pm` |
 
 **Note:** The user can override the autonomy level per-task. E.g., "use level 1 for this task" forces all checkpoints regardless of the project-level setting.
 

package/template/.gemini/skills/pm-orchestrator/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: pm-orchestrator
+description: "PM Agent that orchestrates sequential multi-feature development. Invoke with: 'start pm', 'continue pm', 'stop pm', or 'pm status'."
+---
+
+# PM Orchestrator
+
+Autonomously develops multiple features in sequence using the `development-workflow` skill. Requires **L5 (PM Autonomous)** autonomy level.
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `start pm` | Start a new autonomous session — classify batch, then loop |
+| `continue pm` | Resume after /compact or session restart |
+| `stop pm` | Graceful stop after current feature completes |
+| `pm status` | Show progress summary from pm-session.md |
+
+## Prerequisites
+
+Before starting:
+
+1. **Autonomy Level must be L5.** Read `GEMINI.md` → verify `Autonomy Level: 5 (PM Autonomous)`. If not L5, tell the user and stop.
+2. **Product tracker must have pending features.** Read `docs/project_notes/product-tracker.md` → Features table. If no features have step < 6/6, there is nothing to do.
+3. **Working tree must be clean.** Run `git status`. If dirty, ask user to commit or stash.
+4. **No active PM session.** Check if `docs/project_notes/pm-session.lock` exists. If it does, another PM session may be running — ask user before proceeding.
+
+---
+
+## `start pm` — New Autonomous Session
+
+### Phase 1: Batch Selection
+
+1. Read `docs/project_notes/product-tracker.md` → collect all features with step < 6/6.
+2. **Filter out** features whose dependencies are not yet done (check the Dependencies column and verify the dependency feature has step 6/6).
+3. **Sort** by priority (High > Medium > Low), then by feature ID ascending.
+4. Present the first **1-3 eligible features** to the user as a rolling batch:
+
+```
+PM Orchestrator — Batch Classification
+
+These features are ready to develop:
+
+| # | Feature | Type | Priority | Dependencies |
+|---|---------|------|----------|--------------|
+| 1 | F014 — Short Name | backend | High | F006 (done) |
+| 2 | F015 — Short Name | backend | Medium | none |
+| 3 | F016 — Short Name | fullstack | Medium | F014 |
+
+Classify complexity for each (Simple / Standard / Complex):
+```
+
+5. Wait for user to classify all features in the batch.
+
+### Phase 2: Session Initialization
+
+1. Create `docs/project_notes/pm-session.lock` with content: `session started at {ISO date}`.
+2. Create `docs/project_notes/pm-session.md` from `references/pm-session-template.md`:
+   - Fill **Started** date, **Session ID** (short random ID), **Target Branch** (from `docs/project_notes/key_facts.md` → branching strategy: github-flow → `main`, gitflow → `develop`).
+   - Fill the **Current Batch** table with classified features.
+   - Set **Status** to `in-progress`.
+
+### Phase 3: Orchestration Loop
+
+For each feature in the batch:
+
+#### a. Pre-flight Checks
+
+- **Kill switch**: If `docs/project_notes/pm-stop.md` exists → stop gracefully (go to Shutdown).
+- **Lock**: If `docs/project_notes/pm-session.lock` is missing → stop (session was terminated externally).
+- **Circuit breaker**: If 3 consecutive features are `blocked` → stop and report to user.
+- **Clean workspace**: Run `git status`. If dirty, commit or stash before proceeding.
+
+#### b. Start Feature
+
+1. Update `pm-session.md`: set current feature status to `in-progress`, note step 0/6.
+2. Invoke the `development-workflow` skill:
+   - Command: `start task FXXX as [Simple|Standard|Complex]`
+   - The development-workflow reads L5 → all checkpoints auto-approve.
+   - All quality gates run as normal (tests, lint, build, validators, code review, QA).
+   - At Step 5 (Review): execute `/audit-merge` before the merge checklist evidence.
+
+#### c. Feature Completed (Step 6 done)
+
+1. Verify `docs/project_notes/product-tracker.md` shows the feature at step 6/6 with status `done`.
+2. **Post-merge sanity check**: Run `npm test` (or the project's test command) on the target branch.
+   - If tests **fail** → STOP immediately. The merged feature broke the target branch. Report to user.
+   - If tests **pass** → continue.
+3. Update `pm-session.md`: set feature status to `done`, record approximate duration.
+4. Reset consecutive failure counter to 0.
+
+#### d. Feature Failed
+
+If the development-workflow encounters a failure during any step:
+
+1. The existing retry/fix loop runs (max 3 retries per step, per the `failure-handling.md` reference).
+2. If retries exhausted:
+   - Update `pm-session.md`: set feature status to `blocked`, note the failure reason.
+   - Increment consecutive failure counter.
+   - Skip to the next feature in the batch.
+3. If merge conflicts prevent completion:
+   - Mark as `blocked` with reason "merge conflict".
+   - Skip to next feature.
+
+#### e. Batch Boundary
+
+After each completed or blocked feature:
+
+1. **Re-read** `docs/project_notes/product-tracker.md` to check for newly unblocked features (dynamic dependency resolution).
+2. If the current batch is exhausted and more eligible features remain:
+   - Present the next 1-3 features to the user for complexity classification.
+   - Add them to the batch in `pm-session.md`.
+3. If **3+ features completed** in this session → suggest the user run `/compact` before continuing (context may be getting heavy).
+4. If max session limit reached (**5 features**) → stop and report.
+
+### Phase 4: Shutdown
+
+1. Update `pm-session.md`:
+   - Set **Status** to `completed` (if all done) or `stopped` (if interrupted).
+   - Ensure all feature statuses are up to date.
+2. Remove `docs/project_notes/pm-session.lock`.
+3. Remove `docs/project_notes/pm-stop.md` if it exists.
+4. Print final report:
+
+```
+PM Session Complete
+
+| Feature | Status | Duration | Notes |
+|---------|--------|----------|-------|
+| F014 | done | ~8 min | Clean |
+| F015 | done | ~12 min | 1 QA fix |
+| F016 | blocked | — | Merge conflict |
+
+Completed: 2/3 | Blocked: 1/3 | Remaining: 0
+```
+
+---
+
+## `continue pm` — Resume After /compact or Restart
+
+1. Read `docs/project_notes/pm-session.md`. If it doesn't exist, inform user there is no active session.
+2. **Validate session Status.** If Status is `completed` or `stopped`, inform user the session has ended. To start a new one, delete pm-session.md and run `start pm`.
+3. **Re-create lock.** If `docs/project_notes/pm-session.lock` is missing (e.g., after terminal crash), re-create it with content: `session resumed at {ISO date}`.
+4. Find the feature with status `in-progress`:
+   - Read its ticket file and the product tracker Active Session to determine current step.
+   - Resume the `development-workflow` from that step.
+5. After the in-progress feature completes, re-enter the Orchestration Loop at step (e).
+6. If no `in-progress` feature exists but `pending` features remain, pick the next one and enter step (b).
+
+---
+
+## `stop pm` — Graceful Stop
+
+1. Create `docs/project_notes/pm-stop.md` with content: `stop requested at {ISO date}`.
+2. The orchestration loop will detect this file at the next pre-flight check and shut down gracefully.
+3. The current feature will complete its current step before stopping.
+
+---
+
+## `pm status` — Progress Summary
+
+1. Read `docs/project_notes/pm-session.md`.
+2. Display the Current Batch table and Recovery Instructions.
+3. If no session exists, inform the user.
+
+---
+
+## Guardrails
+
+| Guardrail | Value | Rationale |
+|-----------|-------|-----------|
+| Max features per session | 5 | Model attention degrades after many iterations |
+| Consecutive failure circuit breaker | 3 | Prevent wasting resources on a systemic issue |
+| Kill switch | `pm-stop.md` or `stop pm` | User can always halt the loop |
+| Session lock | `pm-session.lock` | Prevents concurrent PM sessions |
+| Quality gates | Always enforced | Tests, lint, build, validators, code review, QA, `/audit-merge` |
+| Post-merge sanity | `npm test` on target branch | Catch regressions immediately |
+| Rolling batch | 1-3 features | Avoid over-committing; allows dynamic re-prioritization |
+| Clean workspace | `git status` before each feature | Prevent dirty state contamination |
+
+## Edge Cases
+
+1. **Feature mid-execution during /compact**: `continue pm` reads pm-session.md → finds in-progress feature → reads tracker Active Session → resumes development-workflow from that step.
+
+2. **pm-session.md vs tracker disagreement**: Product tracker is the **source of truth**. If pm-session.md says "done" but tracker says "in-progress", trust the tracker and re-verify.
+
+3. **User modifies tracker mid-session**: PM re-reads tracker between features (not mid-feature). Changes take effect at the next feature boundary.
+
+4. **Branch already exists**: development-workflow Step 1 handles this — checks out existing branch and resumes.
+
+5. **L5 selected but `start task` used directly**: development-workflow at L5 behaves exactly like L4 (all checkpoints auto). The PM loop is opt-in via `start pm`, not forced by L5.
+
+6. **Batch classification changes**: User can `stop pm`, edit pm-session.md complexity column, then `continue pm`.
+
+7. **Post-merge sanity check fails**: STOP immediately. The merged feature introduced a regression on the target branch. Do NOT continue — user must investigate manually.
+
+8. **Gemini CLI limitations**: PM Orchestrator instructions are mirrored for Gemini. L5 PM Orchestrator is fully designed for Claude Code; Gemini support is best-effort.
+
+## References
+
+- `references/pm-session-template.md` — Template for the session state file
+- `.gemini/skills/development-workflow/SKILL.md` — The workflow invoked for each feature
+- `docs/project_notes/product-tracker.md` — Source of truth for feature status
+- `.gemini/skills/development-workflow/references/failure-handling.md` — Retry and rollback patterns
+
+## Constraints
+
+- **One feature at a time.** Sequential execution only — no parallel features.
+- **Do NOT skip quality gates.** Even at L5, tests/lint/build/validators/review/QA always execute.
+- **Do NOT force-resolve merge conflicts.** Mark as blocked and skip.
+- **Do NOT modify pm-session.md format.** Follow the template structure exactly.
+- **Do NOT continue after post-merge sanity failure.** Stop and report.

package/template/.gemini/skills/pm-orchestrator/references/pm-session-template.md

@@ -0,0 +1,39 @@
+# PM Autonomous Session
+
+**Started:** {date}
+**Session ID:** {short-id}
+**Autonomy Level:** L5 (PM Autonomous)
+**Status:** in-progress
+**Target Branch:** {main|develop}
+
+## Current Batch
+
+| Feature | Complexity | Status | Duration | Notes |
+|---------|------------|--------|----------|-------|
+| F0XX | Simple | pending | — | — |
+
+## Completed Features
+
+_(Move features here as they complete)_
+
+| Feature | Complexity | Duration | Notes |
+|---------|------------|----------|-------|
+<!-- | F0XX | Simple | ~8 min | Clean | -->
+
+## Blocked Features
+
+_(Move features here if blocked)_
+
+| Feature | Reason | Step |
+|---------|--------|------|
+<!-- | F0XX | Merge conflict | 5/6 | -->
+
+## Recovery Instructions
+
+**Current feature:** (none yet)
+**Branch:** (none yet)
+**Next features:** (see Current Batch table)
+**Blocked:** (none)
+
+To resume after /compact: run `continue pm`
+To stop gracefully: run `stop pm`

package/template/AGENTS.md

@@ -59,6 +59,18 @@ The project includes pre-configured hooks in `.claude/settings.json`:
 
 Personal notification hooks (macOS/Linux) are in `.claude/settings.local.json` — see that file for examples.
 
+## Available Skills
+
+Skills orchestrate multi-step workflows. Invoke by telling the AI assistant what you want to do.
+
+| Skill | Invocation | Description |
+|-------|-----------|-------------|
+| `development-workflow` | `start task F001` | Complete feature development (6-step workflow) |
+| `bug-workflow` | `report bug`, `fix bug` | Bug triage, investigation, and resolution |
+| `health-check` | `health check` | Quick project health scan (tests, build, lint, etc.) |
+| `project-memory` | `set up project memory` | Initialize/maintain docs/project_notes/ |
+| `pm-orchestrator` | `start pm`, `continue pm` | L5: Autonomous multi-feature sequential orchestration |
+
 ## Standards References
 
 - [Base Standards](./ai-specs/specs/base-standards.mdc) — Constitution, methodology, workflow, agents

package/template/CLAUDE.md

@@ -3,7 +3,7 @@
 
 ## Claude-Specific Configuration
 
-<!-- CONFIG: Set your preferred autonomy level (1-4). See base-standards.mdc § Autonomy Levels for definitions. -->
+<!-- CONFIG: Set your preferred autonomy level (1-5). See base-standards.mdc § Autonomy Levels for definitions. -->
 **Autonomy Level: 2 (Trusted)**
 
 <!-- CONFIG: Set branching strategy in docs/project_notes/key_facts.md (github-flow or gitflow) -->
@@ -18,3 +18,4 @@ After context compaction or new session — BEFORE continuing work:
 4. If at Step 5 or later → read `references/merge-checklist.md` and check if the ticket's `## Merge Checklist Evidence` table needs to be filled
 5. Do NOT proceed past any checkpoint without user confirmation (respect autonomy level)
 6. If Active Session shows a pending checkpoint, ask before continuing
+7. If L5 (PM Autonomous) and `docs/project_notes/pm-session.md` exists → read it and run `continue pm` to resume the PM Orchestrator session

package/template/GEMINI.md

@@ -4,7 +4,18 @@
 
 ## Gemini-Specific Configuration
 
-<!-- CONFIG: Set your preferred autonomy level (1-4). See base-standards.mdc § Autonomy Levels for definitions. -->
+<!-- CONFIG: Set your preferred autonomy level (1-5). See base-standards.mdc § Autonomy Levels for definitions. -->
 **Autonomy Level: 2 (Trusted)**
 
 <!-- CONFIG: Set branching strategy in docs/project_notes/key_facts.md (github-flow or gitflow) -->
+
+## Session Recovery (Gemini)
+
+After context loss or new session — BEFORE continuing work:
+
+1. Read product tracker (`docs/project_notes/product-tracker.md`) → **Active Session**
+2. If active feature → read referenced ticket in `docs/tickets/`
+3. Re-read the workflow skill (`.gemini/skills/development-workflow/SKILL.md`) to know what actions the current step requires
+4. If at Step 5 or later → read `references/merge-checklist.md` and check if the ticket's `## Merge Checklist Evidence` table needs to be filled
+5. Respect the autonomy level set above
+6. If L5 (PM Autonomous) and `docs/project_notes/pm-session.md` exists → read it and run `continue pm` to resume the PM Orchestrator session

package/template/ai-specs/specs/base-standards.mdc

@@ -22,7 +22,7 @@ alwaysApply: true
 
 These conventions adapt per-project via `<!-- CONFIG: -->` comments in `CLAUDE.md` and `key_facts.md`:
 
-- **Autonomy Level** → `CLAUDE.md` (1-4)
+- **Autonomy Level** → `CLAUDE.md` (1-5)
 - **Tech Stack** → `backend-standards.mdc` / `frontend-standards.mdc`
 - **Monorepo Layout** → `CLAUDE.md`
 - **Branching Strategy** → `key_facts.md` (github-flow or gitflow)
@@ -59,18 +59,20 @@ Complex:  0 → 1 (+ADR) → 2 → 3 → 4 → 5 (+QA) → 6
 
 Quality gates (tests, lint, build, validators) **always run** regardless of level.
 
-| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto |
-|------------|:-:|:-:|:-:|:-:|
-| Spec Approval | Required | Auto | Auto | Auto |
-| Ticket Approval | Required | Auto | Auto | Auto |
-| Plan Approval | Required | Required | Auto | Auto |
-| Commit Approval | Required | Auto | Auto | Auto |
-| Merge Approval | Required | Required | Required | Auto |
+| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto | L5 PM Auto |
+|------------|:-:|:-:|:-:|:-:|:-:|
+| Spec Approval | Required | Auto | Auto | Auto | Auto |
+| Ticket Approval | Required | Auto | Auto | Auto | Auto |
+| Plan Approval | Required | Required | Auto | Auto | Auto |
+| Commit Approval | Required | Auto | Auto | Auto | Auto |
+| Merge Approval | Required | Required | Required | Auto | Auto |
+| Next Feature | — | — | — | — | Auto |
 
 - **L1 Full Control**: New project or learning SDD — human approves every step.
 - **L2 Trusted**: Comfortable with SDD — AI handles routine, human reviews plans and merges.
 - **L3 Autopilot**: Battle-tested workflow — human only reviews PRs before merge.
 - **L4 Full Auto**: Full automation — human reviews completed features only.
+- **L5 PM Autonomous**: PM Orchestrator runs features end-to-end sequentially. Invoke with `start pm`.
 
 **Auto** = proceed without asking; log in product tracker → "Auto-Approved Decisions" table.
 

package/template/gitignore

@@ -46,3 +46,7 @@ npm-debug.log*
 
 # Claude Code (local settings are personal — hooks, permissions, notifications)
 .claude/settings.local.json
+
+# SDD PM Orchestrator (ephemeral session control files)
+docs/project_notes/pm-session.lock
+docs/project_notes/pm-stop.md