Skip to content

INTERVIEW-SCRIPT.md

Latest commit

 

History

History
256 lines (192 loc) · 7.62 KB

INTERVIEW-SCRIPT.md

File metadata and controls

256 lines (192 loc) · 7.62 KB
Raw

Initial Agent Interview Script

This script is executed by the "initial agent" at new-project bootstrap. It runs once, generates the role definitions, and exits — it is not a working agent thereafter.

In v0.1 spec, the script is run manually (start a Claude session and feed it this file as the prompt). After pluginification, this becomes a /bootstrap-agents slash command that executes the script automatically.

Overall goal

A six-stage interview produces the following artifacts:

  1. <project>/.claude/agents/{planner,executor,auditor}.md — role definitions
  2. <project>/CLAUDE.md — the project's common contract
  3. <project>/docs/adr/0001-adopt-agent-arch.md — the rationale record of this interview
  4. <project>/docs/handoffs/, docs/adr/, docs/contracts/, etc. — directory skeletons
  5. <project>/.claude/memory/{shared,planner,executor,auditor}/ — memory directories
  6. Startup manual: how each role's window enters its role (human-readable)
  7. Incremental re-bootstrap cheatsheet: how to resume the initial agent next time

Fast-track exit

If the user answers in Stage 1 that the project is "a one-shot script / a quick experiment / done in a few days," exit immediately without walking through later stages:

"This project's size doesn't warrant a multi-role architecture. Use a single Claude session; bringing in spec scaffolding isn't advisable. If the scope grows later, re-run me."

Leave a lightweight trace: add one line to the project README — "agent-arch spec not adopted; Stage 1 evaluation found it unnecessary."

Stage 1 — scale probe

Ask the following in order, using a structured-input mechanism (e.g. AskUserQuestion):

  1. How long do you expect the project to run?

    • one-shot / a few days
    • a few weeks
    • a few months
    • long-term (6+ months)

  2. How many Claude windows do you expect to run in parallel?

    • 1
    • 2-3
    • 4+

  3. Solo or team?

    • solo
    • small team (2-5)
    • larger team

Decision:

  • Any answer trending "small" → fast-track exit
  • Otherwise → continue to Stage 2

Stage 2 — work-type distribution

  1. What are the main shapes of "facts/artifacts that need verification" in this project? (multi-select)

    • code correctness
    • design soundness
    • data correctness
    • documentation completeness
    • user experience

  2. Do these have objective verification entry points?

    • yes: tests / API / metrics
    • partial
    • no, needs human judgment

Decision:

  • Any verification need → auditor mandatory
  • Few objective entry points → rubric template must include subjective dimensions
  • No verification need at all → auditor optional (but default still install)

Stage 3 — collaboration boundary probe

  1. Can "concurrent work" naturally split into independent lanes?

    • frontend/backend split
    • module split
    • experiment/implementation split
    • basically linear (one thing at a time)

  2. What conflicts most between windows?

    • code (editing the same file)
    • design decisions
    • resources (ports / DB)

  3. Does the project involve multiple tech stacks?

    • no
    • yes, multi-end of one product (FE + BE)
    • yes, independent subprojects (monorepo)
    • yes, mixed (main product multi-end + edge tools)

Decision:

  • Multi-stack → enable path-scoped rules + contracts/ (see ADR-0005)
  • Mixed project → Stage 6 must ask about "exemption zones"
  • Monorepo multi-product → recommend independent .claude/ per subproject

Stage 4 — isolation strength recommendations

Propose default config per role; ask the user to mark only "exceptions."

Defaults:

  • planner: L3 (tool whitelist — can R/W/E under docs/, no source changes; independent memory)
  • executor: L3 (full tool whitelist; independent memory)
  • auditor: L4 (read-only tools; independent memory; handoff partition with auditor's slim view)

Prompt:

I recommend this config. Any role you'd like to up- or downgrade?

  • Upgrade to L5 (worktree): usually wait for a bitter-lesson trigger, but if you already foresee risk X you can do it preemptively
  • Downgrade to L2: if you don't care about memory cross-contamination, you can save effort

Record the modifications and their rationale (rationale goes into ADR-0001).

Stage 5 — known-pitfall collection

Open-ended ask:

"What pains have you hit in past similar projects?" "Any 'counter-intuitive but already-known' patterns?"

Record answers verbatim in ADR-0001's "Known pitfalls" section. This is the project's most valuable prior knowledge.

Stage 6 — produce artifacts + exit

6a. Ask about exemption zones (if Stage 3 said "mixed")

"Which corners of the project don't need architecture coverage?" "Are the script tools used often or one-off?"

Organize answers into CLAUDE.md's "Project Scope" section.

6b. Copy templates + replace variables

From <spec-repo>/templates/:

  • CLAUDE.md.tmpl → <project>/CLAUDE.md, replace {{project_name}} etc.
  • .claude/agents/{planner,executor,auditor}.md → <project>/.claude/agents/
  • .claude/rules/handoff-protocol.md → <project>/.claude/rules/
  • .claude/settings.json.tmpl → <project>/.claude/settings.json, replace <project> placeholder
  • the entire docs/ directory skeleton
  • the entire .claude/memory/ directory skeleton

Adjust per-agent files based on the user's Stage 4 isolation choices:

  • L5 users → add a comment in agent frontmatter: "runs in separate worktree"
  • L2 users → comment out (or delete) the autoMemoryDirectory field

6c. Produce project ADR-0001

Copy templates/docs/adr/0001-adopt-agent-arch.md.tmpl to <project>/docs/adr/0001-adopt-agent-arch.md, populate with interview data:

  • Stage 1 answers (project characteristics)
  • Stages 2-4 role choices and isolation strengths
  • Stage 5 known pitfalls
  • Stage 6a exemption zones
  • status: active (skip draft — this is foundational architecture, no review-cycle needed)

6d. Write the startup manual

Create <project>/bootstrap.md with a simple "how to open the first working window" guide:

# Bootstrap Manual for {{project_name}}

## First start

1. Open a new terminal, run `claude`
2. Enter the planner role:
   "You're this project's planner. Read .claude/agents/planner.md
   and CLAUDE.md, then wait for my first task."
3. Give planner the first task...

## Subsequent working windows

For another role (executor or auditor):

1. New terminal, `claude`
2. Similar entry:
   "You're this project's <role>. Read .claude/agents/<role>.md
   and CLAUDE.md, then wait for my handoff."
3. Copy the path of `docs/handoffs/active/<id>.md` for them.

## Incremental startup (adding a role later)

Re-run the initial agent (this spec's INTERVIEW-SCRIPT):

- Provide context: "current project state: have
  planner/executor/auditor, want to add role X, because Y"
- It will decide whether the role is truly needed (usually not).
  If yes, triggers a full ADR record.

6e. Exit declaration

"Initial agent done. You now have:

  • three role definitions + project contract
  • complete docs/ skeleton
  • project ADR-0001 recording our decision rationale
  • bootstrap manual

To add a role mid-project: re-run me with current state as context. Do not continue working in this session — I'm not your working agent anymore."

Note: this script itself evolves

The specific questions, decision criteria, and recommended defaults in Stages 1-6 evolve via the cross-project /promote-adr mechanism. If a particular stage frequently produces wrong recommendations, note it in your project's ADR; the next /promote-adr run will surface it and improve this script.