revise-brief

name

revise-brief

description

Update one or more sections of an existing PROJECT_BRIEF.md in a target project folder without re-scaffolding. Lets the user pick which section(s) to refresh (overview, monetization, technologies, architecture, quality-and-profiles, deployment) and delegates to the project-builder subagent to re-run only those define-* skills. Keeps the YAML frontmatter in sync and preserves untouched sections. Use when the target project already has a brief and the user wants to evolve it; use `project-builder` for initial scaffolding or `develop` to build features.

Revise Brief

Entry point for evolving an existing PROJECT_BRIEF.md without re-scaffolding or re-running every question. Use this when:

• The tech stack changed and ## Technologies is stale.
• A new profile was added and ## Profiles needs updating.
• Deployment plans shifted (new cloud provider, new IaC).
• Architecture paths changed and paths.* frontmatter fields need updating.

Do NOT use this skill to scaffold a new project (use project-builder) or to build features (use develop).

Preconditions

• Must run from the root Claude Code session. Spawned subagents cannot spawn further agents.
• The target folder must already contain a PROJECT_BRIEF.md. If not, this skill stops and points the user to project-builder.

Step 1 — Resolve folders

1. Run pwd via Bash to get SESSION_DIR.
2. Ask the user for the target project folder (TARGET_DIR) as an absolute path. Resolve relative paths and confirm.
3. Refuse and re-ask if TARGET_DIR equals, contains, or is contained by SESSION_DIR (path-segment comparison).
4. Confirm <TARGET_DIR>/PROJECT_BRIEF.md exists. If it does not, stop and tell the user to run project-builder first.

Step 1b — Acquire the target project's skills

If <TARGET_DIR>/.claude/skills/ exists, invoke the acquire-project-skills skill via the Skill tool, passing the resolved TARGET_DIR. Skip silently if the folder is absent. See CLAUDE.md § "Acquiring a target project's skills".

Step 2 — Inspect current state

1. Read PROJECT_BRIEF.md.
2. Parse the YAML frontmatter at the top. If the frontmatter is missing or lacks schema_version, stop and tell the user the brief must be migrated by running project-builder against this folder (it will repair the frontmatter on resume).
3. Enumerate the prose sections present (e.g., ## Overview, ## Monetization, ## Technologies, ## Architecture, ## Quality & Standards, ## Profiles, ## Deployment).

Step 3 — Ask what to revise

Present the user with a multi-choice menu of sections to refresh. Use AskUserQuestion and allow multiple selections:

• overview → re-run define-overview (updates frontmatter project.*)
• monetization → re-run define-monetization
• technologies → re-run define-technologies (updates frontmatter stack.* and build.*)
• architecture → re-run define-architecture (updates frontmatter paths.*)
• quality-and-profiles → re-run define-quality-standards (updates frontmatter test.* and profiles, and rewrites both ## Quality & Standards and ## Profiles prose sections)
• deployment → re-run define-deployment (updates frontmatter deployment.*)

If the user selects nothing, stop — there's nothing to do.

Step 4 — Delegate to project-builder in revise mode

Spawn the project-builder subagent via the Agent tool:

• subagent_type: "project-builder"
• mode: "acceptEdits"
• prompt: an instruction block containing:
  • The absolute TARGET_DIR.
  • An explicit REVISE_MODE flag with the ordered list of skills to re-run (exactly what the user selected).
  • A directive: re-run ONLY those skills. Preserve all other prose sections. Preserve all frontmatter fields owned by other skills. Do NOT run the scaffolding step.

Step 5 — Present the diff

After project-builder returns:

1. Read the updated PROJECT_BRIEF.md.
2. Show the user a concise summary of what changed (which sections were rewritten, which frontmatter fields were updated). A full textual diff is optional; a section-by-section summary is usually clearer.
3. Ask whether further revisions are needed. If yes, loop to Step 3.

Constraints

• Never touch SESSION_DIR.
• Never rewrite sections the user did not opt to revise.
• Never change schema_version.
• Never invoke the scaffolding step — this skill evolves the brief, not the project structure.
• If project-builder reports that a requested skill cannot complete (e.g., the user aborted a question), leave the corresponding section untouched and report the state to the user.