Menu
[ADD v0.11.0] Initialize Agent Driven Development — PRD interview + project setup
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
[ADD v0.11.0] Generate or sync a portable AGENTS.md from ADD project state — writes, checks drift, or merges with hand-curated content
[ADD v0.11.0] Declare absence — get autonomous work plan for the duration
[ADD v0.11.0] Return from absence — get briefing on autonomous work
[ADD v0.11.0] View project branding — accent color, palette, drift detection, image gen status
[ADD v0.11.0] Update project branding — new colors, fonts, tone, audit artifacts
[ADD v0.11.0] Generate or refresh CHANGELOG.md from conventional commits
| name | add-init |
| description | [ADD v0.11.0] Initialize Agent Driven Development — PRD interview + project setup |
| argument-hint | [--reconfigure] [--quick] [--defaults] [--sync-registry] |
Codex interaction mode notice (ADD)
This skill depends on structured question/answer turns. Behavior depends on Codex's current mode:
- Plan mode: call the
ask_user_questiontool for each prompt below. One question per call. Wait for the user's answer before moving on.- Default mode (no
ask_user_questionavailable): emit the questions inline as a numbered list, then halt and wait for the user's next prompt. Do not improvise, infer, or fabricate answers — this skill fails closed if required input is missing. Resume only after the user replies.The skill body below defines what to ask; the shim only governs how to ask.
Initialize Agent Driven Development for this project. This command conducts a structured interview to understand the project, then scaffolds the full ADD framework.
| Flag | Purpose | Questions | Target user |
|---|---|---|---|
| (none) | Full interview — detects adoption vs greenfield, runs Phases 0-5 | ~12 | New projects with non-trivial scope or existing codebases |
--quick | Greenfield fast path — 5 essential questions, sensible defaults elsewhere | 5 | Prototypes, solo projects, time-constrained onboarding |
--defaults | True non-interactive init — every value derived or defaulted, zero questions | 0 | Headless sessions (claude -p, codex exec), CI pipelines |
--reconfigure | Re-run interview preserving existing answers as defaults | ~12 | Updating an already-initialized project |
--sync-registry | Read-only: reconcile ~/.claude/add/projects/{name}.json with ground truth | 0 | Fixing drift detected by the registry-sync rule |
--quick)Greenfield fast path. Skips adoption detection, skips profile-derived questions, and defaults anything that isn't one of the 5 essential answers. Use when you want ADD initialized in ~2 minutes.
{current_dir_name})"Everything else that the full interview asks is defaulted:
| Area | Quick-mode default |
|---|---|
| PRD depth | 1-pager generated from (name, stack, scope-paragraph prompt) |
| Quality mode | strict for beta/ga, standard for alpha, spike for poc |
| CI/CD provider | Inferred from .github/ if present, otherwise none |
| Commit convention | Conventional commits |
| Protected branches | [main] |
| Coverage threshold | 80% at beta/ga, 50% at alpha, 0 at poc |
| Branding palette | Default ADD raspberry (#b00149) until /add-brand is run |
| Image generation | enabled: false, nudged: false |
--quick skips--quick still does.add/config.json, .add/learnings.json (empty), docs/prd.md (1-pager), specs/ (dir), docs/plans/ (dir)~/.claude/add/projects/{name}.json)maturity=ga + tier=1)After quick init, the user can always run /add-init --reconfigure for the full interview, or run /add-spec to start formalizing features. Specs created under a quick-init project are no different from specs created under full init.
--defaults)True non-interactive init. Asks zero questions — no ask the user (use a clear, single-question prompt) calls, no interview turns, no confirmation prompts. Every value is derived from the project or defaulted. Designed for headless one-shot sessions (claude -p "/add-init --defaults", codex exec "/add-init --defaults") and CI pipelines, where there is no second turn to answer a question in.
Before doing anything else, check for .add/config.json. If it exists, print a notice and stop — touch nothing:
.add/config.json already exists — /add-init --defaults never overwrites an
initialized project. Run /add-init --reconfigure to refresh the configuration.
| Field | Defaults-mode value |
|---|---|
| Project name | Basename of the current working directory |
| Language | Auto-detected from manifest files: package.json → typescript (if tsconfig.json or TS deps) else javascript, pyproject.toml/setup.py → python, go.mod → go, Cargo.toml → rust, Gemfile/*.gemspec → ruby; fallback unknown |
| Environments | ["local"], no autoPromote |
| Maturity | poc (greenfield) or the evidence-based detected level (adoption path) — no confirmation question either way |
| Operating mode | autonomous |
| Scope paragraph | Omitted — PRD stub notes "run /add-spec to define scope" |
| Quality mode, coverage, branding, etc. | Same defaults table as --quick |
--defaults skipspoc) level is applied directly--quick asks at the end--defaults still does.add/config.json, .add/learnings.json (empty), docs/prd.md (stub noting "run /add-spec to define scope"), specs/ (dir), docs/plans/ (dir)~/.claude/add/projects/{name}.json)--sync-registry unchangedSame as --quick: run /add-init --reconfigure any time for the full interview, or /add-spec to start formalizing features.
--sync-registry)Reconciles ~/.claude/add/projects/{name}.json against the project's ground truth. Triggered automatically by the registry-sync.md rule when drift is detected at session start, or manually by the user.
Read-only in the project; writes only to the cross-project registry file. Shows a diff before writing:
REGISTRY RECONCILIATION for {project}:
learnings_count: 5 → 55
last_retro: null → {date}
maturity: alpha → beta
Apply? [yes/no]
Does not run the interview. Does not touch .add/config.json.
.add/config.json already exists--reconfigure flag, display current config summary and ask if reconfiguration is wanted--reconfigure flag, proceed with interview (preserving existing answers as defaults)--defaults flag, print the existing-config notice (see Defaults Mode) and exit without touching anythingCheck if ~/.claude/add/profile.md exists. This file carries preferences across projects.
Also check ~/.claude/add/library.md for cross-project learnings and
~/.claude/add/projects/ for previous project history.
If profile exists:
Read it and use preferences as defaults throughout the interview. Also read
~/.claude/add/library.md for cross-project knowledge. Announce this:
I found your ADD profile with preferences from previous projects.
I'll use these as defaults — you can override anything during the interview.
Your profile preferences:
Stack: {languages, frameworks from profile}
Cloud: {provider from profile}
Process: {autonomy, quality mode from profile}
Previous ADD projects: {list from ~/.claude/add/projects/}
This can dramatically shorten the interview — if the profile matches, Section 2 might only be 2-3 confirmation questions instead of 6-8.
If no profile exists: This is a first-time ADD user. After the interview, offer to create one:
This is your first ADD project. After setup, I can create a user
profile (~/.claude/add/profile.md) so future projects inherit your
preferences and the interview gets shorter. Want me to create it?
If .add/config.json does NOT exist AND the project contains existing project files (CLAUDE.md, .claude/, specs/, tests/, CI/CD, docker-compose.yml, git history, etc.), automatically enter adoption mode. This is non-destructive — ADD absorbs and complements existing methodology.
Silently scan the project for existing methodology without asking the user:
□ CLAUDE.md — read it, extract project description and existing commands
□ .claude/rules/ — list existing rules, note coverage areas
□ .claude/skills/ — list existing skills, note what ADD would add
□ .claude/settings.json — read permissions
□ specs/ or .add/specs/ — list existing feature specifications
□ docs/ or docs/plans/ — list existing implementation plans
□ tests/ — identify test framework, coverage, directory structure
□ .github/workflows/ — identify CI/CD pipelines
□ .gitlab-ci.yml / Jenkinsfile — alternative CI/CD
□ docker-compose.yml — identify containerization strategy
□ Dockerfile — identify containerization
□ package.json / pyproject.toml / Cargo.toml / go.mod — identify stack
□ .git/config — identify git remote host and repository
□ .pre-commit-config.yaml — identify existing git hooks
□ .env.example — identify environment variables and secrets strategy
□ PROJECT_STATUS.md or similar — identify session tracking / status history
After silent detection (and the maturity assessment below), show the user a structured summary of what exists vs. what ADD adds: existing methodology, existing infrastructure, what ADD would add (non-destructive), what ADD would preserve untouched — then ask "Proceed with adoption?". Render per ~/.codex/add/templates/init-output-examples.md (Adoption Findings Panel).
Assess project maturity using evidence-based scoring. This assessment is BINDING — maturity is determined by what the project actually demonstrates, not by aspiration.
Score each of these 12 evidence categories as present or absent (git timestamps, configs, and CI files are the detection sources): specs, tests, coverage threshold (20% = alpha signal, 50% = beta, 80% = ga), CI/CD pipeline, PR-based branching, conventional commits (sample last 20 commits), environment separation, release tags, protected branches, TDD evidence (tests predate/accompany implementation), spec-driven evidence (specs predate implementation), and quality gates (pre-commit hooks, CI checks, linting).
Scoring: POC 0–2 items · Alpha 3–5 · Beta 6–8 · GA 9+.
For the full maturity cascade matrix and promotion process, see ~/.codex/add/references/maturity-matrix.md.
Present the assessment authoritatively — do NOT ask the user to confirm or override the level. Compact example:
MATURITY ASSESSMENT (evidence-based):
Your project operates at: ALPHA
Evidence: ✓ tests (47% coverage) ✓ CI/CD ✓ conventional commits · ✗ 9 other items
Score: 3/12 evidence items → ALPHA
Gap to Beta: specs (/add-spec), coverage >50%, PR workflow, 2+ environments, TDD evidence
Render the full panel (per-item ✓/✗ list, gap checklist, promotion note) per ~/.codex/add/templates/init-output-examples.md (Maturity Assessment Panel).
If the user disagrees with the assessment, explain that ADD maturity is evidence-based and that promotion happens through /add-retro when criteria are met. The user can start at the detected level and promote quickly if the project genuinely meets higher criteria.
Adoption mode runs a SHORTER interview because many answers are detected:
Section 1 (Product): If CLAUDE.md exists with a project description, skip most questions. Just confirm:
From your CLAUDE.md, I understand this project:
{Extracted description from CLAUDE.md}
Is that still accurate? Anything to add or clarify?
Otherwise, run standard Section 1 questions (4 questions, ~3 min).
Section 2 (Architecture): Nearly all answers are detected from project files. Just run confirmations:
I detected your tech stack from your project files:
Language: {detected}
Backend: {detected}
Frontend: {detected}
Database: {detected}
Containers: {detected}
Git: {detected}
CI/CD: {detected}
Does this match your current setup? Anything to add or correct?
Then ask the 3 process questions from Section 3 (autonomy, quality mode, team size).
Total adoption interview: ~5-8 questions, ~5 minutes (vs. 14-16 questions in greenfield mode).
ADD's rules are NOT copied into the project — they are injected each session by the plugin's SessionStart hook (load-rules.sh), maturity-gated, and update automatically with the plugin. /add-init never writes to .claude/rules/.
For each existing rule in the project's .claude/rules/, check for overlap with ADD's rule set:
If an existing project rule covers similar ground as an ADD rule: Ask the user:
You have an existing rule: {existing_rule.md}
This covers similar ground as ADD's {add_rule} (injected automatically each session).
Options:
a) Keep your rule as-is — it takes precedence where they conflict
b) Trim your rule to only the parts ADD doesn't cover
c) Remove your rule — rely on ADD's injected version
If a stale ADD rule copy exists (same name as a plugin rule, or add- prefixed — left behind by an ADD version before v0.9.11 that copied rules): recommend removal, since the hook now injects the current version and the copy will drift:
.claude/rules/{name}.md matches an ADD plugin rule. ADD now injects rules
at session start — this copy is redundant and will go stale. Remove it?
For each ADD skill (e.g., /add-spec, /add-plan, /add-away, /add-back, /add-retro):
If project has equivalent skill: Ask:
You have an existing skill: {existing_skill}
ADD provides {add_skill} which extends this.
Keep yours, use ADD's, or should I merge them?
If project doesn't have it: Add the ADD skill to .claude/skills/.
Priority: Project's existing skills are preferred unless the user wants ADD's version or a merge.
NEVER overwrite an existing CLAUDE.md.
Instead, append an ADD methodology section at the end:
## ADD Methodology
This project follows Agent Driven Development (ADD) for structured code generation and knowledge persistence.
**Configuration:** `.add/config.json`
**Knowledge Base:** `.add/learnings.md` (auto-populated during development)
**Quality Gates:** Enforced via `/add-verify` command
**Workflow:** `/add-spec` → `/add-plan` → `/add-tdd-cycle` → `/add-retro`
See `.add/config.json` for detailed settings.
If the project already has specs in a custom location (e.g., specs/spike/, doc/specs/, or other):
DON'T move or rename them.
DO create .add/config.json pointing to the existing specs directory:
"specs_directory": "specs/spike/",
"specs_format": "markdown"
Ask the user:
Your feature specs are currently in {location}.
Should I continue using that directory for ADD specs,
or create a fresh specs/ directory for ADD-formatted specs?
For mature projects, seed .add/learnings.md with initial knowledge instead of a blank template:
Present the seed entries to the user for confirmation:
I've extracted initial learnings from your project history:
PATTERNS & CONVENTIONS:
- {pattern 1 from CLAUDE.md}
- {pattern 2 from git history}
COMMON ISSUES & SOLUTIONS:
- {issue 1} → {solution from git log}
- {issue 2} → {solution from recent commits}
These will populate .add/learnings.md as the starting knowledge base.
Any additions or corrections before I finalize?
After confirming maturity level and completing the adoption interview, generate a gap analysis comparing current project state against the confirmed maturity level requirements (per the cascade matrix in ~/.codex/add/references/maturity-matrix.md):
CATCH-UP ANALYSIS: Bringing {project} to {MATURITY} compliance
REQUIRED FOR {MATURITY}: STATUS:
PRD document {✓ exists | ✗ missing}
Feature specs {✓ N specs found | ✗ missing for N features}
Implementation plans {✓ N plans found | ✗ missing}
Quality gates configured {✓ N gates active | ✗ not configured}
TDD coverage at threshold {✓ N% meets threshold | ✗ N% below threshold}
CI/CD pipeline {✓ active | ✗ not found | ○ not required at this level}
Milestone structure {✓ found | ✗ missing | ○ not required at this level}
Source control workflow {✓ matches | ⚠ partial | ✗ missing}
SCORE: {N}/{TOTAL} requirements met
CATCH-UP ITEMS (if score < 100%):
1. {item — e.g., "Generate docs/prd.md from existing CLAUDE.md + brief interview"}
2. {item — e.g., "Create retroactive specs for auth, billing features"}
3. {item — e.g., "Configure 3-gate quality pipeline"}
If catch-up items exist, ask:
I can generate a catch-up cycle to bring your project to {MATURITY} compliance.
This would take approximately {estimate} of autonomous work.
Options:
a) Run catch-up spike now (I'll work autonomously)
b) Save as first cycle plan (you review first)
c) Skip — I'll adopt ADD alongside your existing workflow
If option (a) or (b):
.add/cycles/cycle-0-catchup.md with the gap items as work itemsDisplay what was newly created, what was enhanced, what was preserved exactly as-is, the resulting configuration (stack, tier, quality, autonomy), and next steps. Render per ~/.codex/add/templates/init-output-examples.md (Adoption Summary Panel).
Conduct a structured 1-by-1 interview following the human-collaboration rule. Always estimate total questions upfront.
Welcome to Agent Driven Development (ADD).
I'll interview you across 4 sections to understand your project:
Section 1: Product (4 questions, ~3 min)
Section 2: Architecture & Tech Stack (6-8 questions, adaptive, ~5 min)
Section 2.5: Branding (1-2 questions, ~1 min)
Section 3: Process & Collaboration (5 questions, ~4 min)
Total: approximately 16-19 questions, ~12 minutes.
Some questions are adaptive — I'll skip what I can detect automatically.
Your answers will generate:
- docs/prd.md (Product Requirements Document)
- .add/config.json (project configuration)
- .claude/settings.json (Claude Code settings)
- specs/ directory (for feature specifications)
- docs/plans/ directory (for implementation plans)
Let's begin.
Load the question bank — verbatim Q1–Q18 prompts plus ask the user (use a clear, single-question prompt) options — from ~/.codex/add/templates/init-interview.md. Ask questions ONE AT A TIME, building on previous answers. Phase structure and branching logic:
Section 1: Product (Q1–Q4, ~4 questions) Problem/value proposition (Q1), primary users (Q2), success metrics (Q3), MVP scope in/out (Q4).
Section 2: Architecture & Tech Stack (Q5–Q13, ~6-8 questions, adaptive)
Before asking tech questions, run the silent detection step (do not show to user): check for package.json, pyproject.toml/requirements.txt, Cargo.toml, go.mod, pom.xml/build.gradle, docker-compose.yml, Dockerfile, .github/workflows/, .gitlab-ci.yml, Jenkinsfile, .git/config, terraform/.tf files, Makefile/justfile. If project files are detected, summarize what you found before asking Q5.
.git/config remote is detected, otherwise ask.Section 2.5: Branding (Q13.5, ~1 min)
"Yes — let me share it" → parse hex color, fonts, tone, logo path, and style-guide source into branding.*, generating the palette per ~/.codex/add/templates/presets.json. "No — use ADD defaults" → raspberry preset (#b00149) from presets.json, optionally offering the preset picker (Raspberry / AI Purple / Ocean / custom hex). Branding can always be updated later with /add-brand-update.
Section 3: Process & Collaboration (Q14–Q18, ~4 min)
/add-retro when criteria are met). If POC is selected, explain the relaxed process per the question bank.Thanks for the thorough answers. I have everything I need to set up ADD.
Generating:
1. docs/prd.md — your Product Requirements Document
2. .add/config.json — project configuration
3. Project directories and scaffolding
The standard ADD layout. See ~/.codex/add/rules/project-structure.md for the full specification.
# ADD methodology directories (committed to git)
mkdir -p .add .add/retros .add/away-logs
# Specification and planning directories
mkdir -p specs docs/plans
# Milestone and cycle tracking
mkdir -p docs/milestones .add/cycles
# Test artifact directories
mkdir -p tests/screenshots tests/screenshots/errors tests/e2e tests/unit tests/integration
# Claude Code config
mkdir -p .claude
If CHANGELOG.md does not already exist in the project root, create it from the changelog template:
~/.codex/add/templates/changelog.md.templateCHANGELOG.md in the project rootThis gives the project a Keep a Changelog-formatted changelog from day one. The /add-changelog command and the push hook will populate it automatically as development proceeds.
# ADD user-level persistence (outside any project)
mkdir -p ~/.claude/add ~/.claude/add/projects
Append ADD-specific entries if not already present:
# ADD — ephemeral artifacts (don't commit)
.add/away-logs/
tests/screenshots/errors/
# ADD — these SHOULD be committed (don't ignore)
# .add/config.json
# .add/learnings.md
# .add/retros/
# specs/
# docs/plans/
# tests/screenshots/{feature}/
ADD rules are NOT copied into the project. The plugin's SessionStart hook (load-rules.sh) injects the active rule set every session, gated by the project's maturity level — rules stay current with the plugin and never drift. (Versions before v0.9.11 copied 10 rules into .claude/rules/; that mechanism is retired because copies went stale and, after v0.9.9, duplicated the hook injection.)
This phase only checks for leftovers:
.claude/rules/ exists, list its files and compare basenames against ~/.codex/add/rules/ (also match add- prefixed variants).Found {N} ADD rule copies in .claude/rules/ from an earlier ADD version:
{list}
ADD now injects current rules at session start, so these are redundant
and will go stale. Remove them? (user-authored rules are untouched)
Read ~/.codex/add/templates/config.json.template and fill in all placeholders with interview answers. Use the Write tool.
Ensure the generated config includes the maturity field:
{
"maturity": {
"level": "{poc|alpha|beta|ga}",
"promoted_from": null,
"promoted_date": null,
"next_promotion_criteria": "{what's needed for the next level}"
}
}
Read ~/.codex/add/templates/prd.md.template and fill in all placeholders with interview answers. Write a real PRD — don't leave template placeholders. Every section should have substantive content based on the interview answers.
Read ~/.codex/add/templates/settings.json.template. Customize permissions based on the tech stack detected.
The template includes a statusLine configuration that displays /ADD:enabled in the Claude Code status bar (with "ADD" in raspberry #b00149). This provides an at-a-glance indicator that the project is ADD-managed. If the user already has a custom statusLine in their settings, ask before overwriting it.
Read ~/.codex/add/templates/CLAUDE.md.template. Fill in project-specific information:
If CLAUDE.md already exists, ask before overwriting. Offer to append ADD-specific sections instead.
Read ~/.codex/add/templates/learnings.md.template and fill in the project name. This is the knowledge base that agents build over time through automatic checkpoints. Committed to git so it transfers between devices.
Invoke /add-agents-md to generate a portable AGENTS.md at project root. This is the cross-tool open standard — any agent (Cursor, Codex CLI, Copilot, Windsurf, etc.) reading the repo will pick it up. Generation is maturity-aware: POC projects get a minimal bullet summary, Alpha+ projects get a sectioned doc. If an AGENTS.md already exists without the ADD marker block, skip this step and recommend the user run /add-agents-md --merge after init completes.
If ~/.claude/add/profile.md does NOT exist and the user agreed to create one:
Read ~/.codex/add/templates/profile.md.template, fill in preferences from the interview, and write to ~/.claude/add/profile.md.
If profile already exists, do NOT modify it — profile updates only happen during /add-retro.
Write a snapshot to ~/.claude/add/projects/{project-name}.json:
{
"name": "{PROJECT_NAME}",
"path": "{ABSOLUTE_PROJECT_PATH}",
"initialized": "{DATE}",
"last_retro": null,
"stack": ["{lang-version}", "{framework}", ...],
"tier": {N},
"cloud": "{provider}",
"key_learnings": []
}
This lets future /add-init calls on new projects reference your history:
"I see you worked on {project} with {stack}. Similar setup here?"
If ~/.claude/add/library.md does NOT exist, create it from ~/.codex/add/templates/library.md.template.
If it exists, leave it alone — it's updated during /add-retro.
Display an "ADD initialized successfully" panel covering: project structure created (per-file ✓ list), rules installed / skipped / prefixed (from Phase 2.5 tracking), cross-project files, the 3-tier knowledge cascade (plugin-global knowledge/global.md → user-local ~/.claude/add/library.md → project .add/learnings.md), the resolved configuration (stack, infrastructure, tier, maturity, quality + coverage threshold, autonomy, branching), and what's committed vs machine-local (with the /add-init --import note). Render per ~/.codex/add/templates/init-output-examples.md (Phase 5 Init Summary Panel).
Display exactly ONE next-steps block based on maturity level and config — do NOT show all three. Block text is in ~/.codex/add/templates/init-output-examples.md (Persona-Aware Next Steps Blocks):
collaboration.team_size > 1, OR user said "PM" or "product manager" during the interview, OR autonomy = "guided") → product-person block (/add-spec and /add-verify only).End-of-skill epilogue: follow ~/.codex/add/references/skill-epilogue.md (observation + learning checkpoint + progress tracking).