Spec Driven DevelopSAFE

Spec-driven development workflow for AI coding agents: architecture-first planning, task decomposition, GitHub Issue/PR tracking, Deep Discuss, and adaptive control for Claude Code, Codex, Cursor, and other Markdown-capable agents.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: spec-driven-develop
description: >-
  Automates pre-development workflow for large-scale complex tasks. Use when the user
  mentions "rewrite", "migrate", "overhaul", "refactor entire project", "transform",
  "rebuild in [language]", "spec-driven", or describes any large-scale project transformation
  that requires planning before coding. Also triggers on Chinese keywords: "改造", "重写",
  "迁移", "重构", "大规模", "规范驱动". Performs full project analysis, task decomposition,
  documentation generation, project-level instruction and native memory surface resolution,
  progress tracking setup, and then executes the plan within the same session. Keeps Issues as
  task-tracking units while batching related implementation into coherent reviewable PRs.
metadata:
  version: 1.15.0
---

# Spec-Driven Develop

You are executing the **Spec-Driven Development** workflow — a seven-phase pipeline (Phases 0-6) for large-scale complex tasks. Complete preparation phases (analysis, planning, progress setup), then execute the plan — all within a single session.

**Behavioral rules**: `references/behavioral-rules.md` — read and follow them in every phase; they are non-negotiable.

## Configuration

| Path | Default Value | Purpose |
|:-----|:--------------|:--------|
| Analysis output | `docs/analysis/` | Phase 1 analysis documents |
| Plan output | `docs/plan/` | Phase 3 planning documents |
| Progress output | `docs/progress/` | Phase 4 tracking documents (incl. MASTER.md) |
| Instruction surfaces | Resolved per project | Project-level constraints for agents (see Phase 4) |
| Memory surface | Native first | Durable facts via the agent's native memory when available; repo fallback only when explicitly selected |
| Archive output | `docs/archives/<project>/` | Phase 6 archived artifacts |
| Task tracking mode | Auto-detect | `GITHUB_FULL`, `GITHUB_STANDARD`, or `LOCAL_ONLY` |
| Delivery batching | Phase-first | Issues track tasks; PRs integrate coherent task batches |
| Adaptive control | Enabled | Drift thresholds: annotate=20%, replan=40%, rescope=60% of phase tasks |

**Canonical references** (each topic has exactly one home — cite it, never re-explain it):

| Reference | Owns |
|:----------|:-----|
| `references/behavioral-rules.md` | All behavioral rules (1-19) |
| `references/github-integration.md` | Tracking modes, pre-flight check, all `gh` commands and Issue/PR body templates |
| `references/adaptive-control.md` | Telemetry collection, drift calculation, response actions, state storage, controller activation |
| `references/parallel-protocol.md` | Dispatch/review admission (tiers), lane/worktree protocol, review loop, merge risk, post-integration checks |
| `references/super-philosophy.md` | S.U.P.E.R principles + the 10-check review checklist |
| `references/templates/` | Schemas for every generated document (analysis, plan, progress, governance, archive) |

**Task tracking modes** (capabilities differ; detection and upgrade instructions live in `references/github-integration.md` § "Pre-flight Check"):

- **GITHUB_FULL**: Issues + Milestones + Labels + Project board + worktrees + batch PRs
- **GITHUB_STANDARD**: same minus the Project board
- **LOCAL_ONLY**: original local-file workflow, no GitHub dependency

## Before You Begin: Cross-Conversation Continuity Check

**CRITICAL**: Before starting any phase, inventory and read any existing project-level instruction and memory surfaces (`AGENTS.md`, `CLAUDE.md`, existing platform rule files, the active agent's native project memory, any repo-local fallback memory file already declared by the project or by an existing `docs/progress/MASTER.md`).

Then check if `docs/progress/MASTER.md` already exists:

- If it **exists**: Read it immediately. You are resuming an in-progress task. Identify the tracking mode, current phase, and completed work; continue from the exact point where the previous conversation left off. Do NOT restart from Phase 0.
  - **In GitHub modes**: Also query GitHub for the latest task status — see `references/github-integration.md` § "Reading Progress from GitHub". Update MASTER.md if GitHub state is ahead of the local index.
- If it **does not exist**: This is a fresh start. Proceed to Phase 0.

After loading your current state, populate the platform's native task tracking tool (e.g. TodoWrite) with the active phase's pending tasks: content = task description, status = in-progress for the active task, priority mapped P0=high, P1=medium, P2=low. If no native task tool is available, skip this step — MASTER.md alone is sufficient.

---

## Phase 0: Quick Intent Capture

**Goal**: Capture the user's high-level transformation direction in 1-2 sentences — just enough to give Phase 1 analysis a focus.

**Actions**:

1. Extract from the user's message: the transformation type, the rough target state, and any explicitly stated constraints.
2. Summarize the direction back in 1-2 sentences. Do NOT ask deep clarifying questions here — Phase 1 analysis will reveal what to ask. Confirm: "I understand you want to [direction]. Let me first analyze the current project so I can ask you the right questions."
3. If intent is completely unclear, ask ONE high-level question to determine the transformation type.

**Output**: A preliminary direction statement guiding Phase 1. NOT the final task definition — that comes in Phase 2.

---

## Phase 1: Deep Project Analysis

**Goal**: Build a comprehensive understanding of the current codebase, informed by the Phase 0 direction.

**Actions**:

1. Launch `project-analyzer` sub-agents **in parallel**, split by focus area:
   - **Architecture & Stack**: structure, directory layout, tech stack, entry points, build/run commands
   - **Module Inventory**: each module's responsibility, public API surface, size, dependencies — evaluated against all five S.U.P.E.R principles with a per-principle compliance rating
   - **Risks, Tests & Governance**: transformation risks, complexity hotspots, coding conventions, test cove

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

- All API keys and webhook URLs read from environment variables?

Gates applied: no_behavioural_pass.