olamedia/architect

Architect

CRITICAL: MUST NOT advance to the next phase or step without explicit user permission. Complete the current step, present the result, and wait for the user to say to move forward. Never batch multiple steps in one turn. Never anticipate the next step by pre-reading, pre-scanning, or pre-preparing for it. When the user says nothing to add or nothing to fix — that IS permission to proceed. Do not ask again.

CRITICAL: During Step 1 (collecting intent), MUST NOT read any codebase files, scan directories, check context sources, or run research. The ONLY action allowed is writing the Intent block into requirements.md from the user's words. Research starts in Step 2, AFTER the user confirms the intent draft is complete.

CRITICAL: During Step 1, ALL user input is source material for the Intent block. References to folders, files, prior artifacts, context hints — everything the user says goes into Intent. Record it, update requirements.md, and ask if there is more. Do not act on references until research starts.

CRITICAL: Each phase and step has its own purpose and scope. Do NOT mix them. Intent collects the user's words — no analysis, no conclusions. Research collects codebase facts into context-map.md — factual notes about what the code does ARE research output; what is NOT allowed is solution ideas or design decisions. Stories extract from intent and map — no design. Design documents structure — no open questions (those belong in requirements). Tasks break down design — no redesign. Stay in scope.

CRITICAL: MUST NOT speak questions to the user before they are written into requirements.md. Write first, present after. No exceptions. Verbal summaries of document content are fine; verbal questions that aren't in the document yet are a violation.

CRITICAL: Any change to requirements, design, or tasks MUST propagate starting from Phase 1. If something needs changing mid-pipeline, go back to requirements.md first, update intent/stories there, then propagate forward through design and tasks. Never patch a downstream artifact without updating upstream first.

Turn a raw idea into planning artifacts: context-map.md, requirements.md, design.md, tasks.md, and optionally compiled issues or testing notes. Research is not its own phase — refresh context-map.md whenever research runs. Everything through Phase 3 is read-only on the product codebase.

Phase detail sits in references/ (phase-1-requirements.md through phase-4-compile.md, plus research.md, formats.md, context-sources.md, issues-as-intent.md, human-techtalk.md, testing-notes.md).

When to Use

• A feature needs separate reviewable requirements, design, and tasks
• The problem benefits from iterative refinement before coding

Skip when: obvious single-file fix, only one phase applies, or upstream artifacts already exist and you resume from the right phase.

Input

• The idea or problem
• Artifact folder path — if none given, ask (e.g. docs/plans/...) and create it

Output

An artifact folder containing:

• context-map.md — living document, updated throughout
• requirements.md
• design.md
• tasks.md
• tasks/task-N.md — optional, from Phase 4
• testing-notes.md — optional, from Phase 4

Pipeline

Phase 1: Requirements + Research → Phase 2: Design → Phase 3: Tasks → Phase 4 (optional)
  ↑__________________________________|__________________|
  (return to Phase 1 if gap found)

All research and open questions MUST be settled in Phase 1. Phases 2–4 consume context-map.md and requirements.md only. If a gap is found at any later phase, return to Phase 1, resolve it there, then resume.

Phase 1: Requirements

See phase-1-requirements.md.

1. Collect the idea — intent in user's own words
2. User confirms draft → mandatory first research → save context-map.md
3. Extract user stories from intent and map
4. Questions loop — add [to-ask] items, research when codebase can answer, loop until no open questions remain
5. Save requirements.md

Gate: confirm, then ask whether to continue to design. Use structured questions.

Phase 2: Design

See phase-2-design.md.

• Load requirements.md and context-map.md
• Document components, data flow, dependency graph, decisions, integrations, risks
• If unknowns surface, return to Phase 1 — do not research inside Phase 2
• Save design.md

Gate: confirm, then ask whether to continue to tasks. Use structured questions.

Phase 3: Tasks

See phase-3-tasks.md.

• Overview and task graph first
• Ordered tasks with acceptance criteria
• Mandatory grouping pass — merge overly small tasks
• Phase checkpoints
• Save tasks.md

Gate: confirm, then ask whether to continue to Phase 4 (compiled issues, testing notes, or both). Use structured questions.

Phase 4 (optional)

Two independent outputs — either or both may run.

• Compiled issues (tasks/task-N.md) — self-contained scope, checklist, acceptance criteria, do-not-touch items, rare notes. See phase-4-compile.md.
• Testing notes (standalone testing-notes.md or appended to compiled tasks) — scenarios derived from user-story acceptance criteria. See testing-notes.md.

Research

Research belongs to Phase 1. Full process in research.md.

• Mandatory: after user confirms initial idea → seeds context-map.md
• During Phase 1: whenever new requirements mention types, APIs, components, or DTOs not in the map
• After Phase 1: if a gap is found during design or tasks, return to Phase 1 to research and resolve it — do not research inline in later phases
• Rule: if something is not in context-map.md, it must be discovered in Phase 1 before you rely on it

After every research run, update context-map.md before other artifacts.

Behavioral Baseline

Across all phases:

• Don't assume silently. State assumptions. Multiple interpretations? List them, don't pick. Something unclear? Stop, name the gap, ask.
• Nothing speculative. Minimum output that solves the ask. No extra features, unrequested flexibility, impossible-case handling.
• Surgical edits. Touch only what changed — don't rewrite unaffected sections. Match existing style. Orphans your diff created: remove. Pre-existing dead content: leave unless asked.
• Goal-driven. Tie work to verifiable criteria. Multi-step: numbered plan, verify step each.

Design Certainty Rule

design.md must not contain uncertain language (may/might/could/should/perhaps/TBD/to be confirmed/needs investigation/depending on) or research instructions (need to check/look into/verify later). If you cannot write a definitive statement, the gap belongs in requirements.md as a [to-ask] question — resolve it in Phase 1 before writing it into the design.

Self-check: After writing design.md, re-read the entire file and search for: may, might, could, should, perhaps, if, either/or, investigate, verify, check, ask, TBD, need to, depends on, possibly. Every hit is a flag — move it to requirements.md as a [to-ask] question, step back to Phase 1, research or ask, then mark [resolved] with the answer. Return to design only after all new questions are resolved.

Change Propagation

When a requirement changes at any phase:

1. Describe the impact on requirements, design, and tasks together
2. Wait for agreement
3. Apply edits in one batch

Never edit docs one at a time without confirming the full set of changes.

Gates

Confirm between phases. If the user revises an earlier phase, propose downstream updates in one batch after they agree, then continue. Stopping early is fine — resume from the right phase.

Refuse: tasks without written requirements, skipped gates, or "I know the repo" instead of an updated map. Do not skip the first research pass.

Structured Questions

When presenting choices to the user, use the IDE's structured question tool (AskQuestion in Cursor, or equivalent in other IDEs) if available. Applies to:

• Gates — "Continue to [next phase]" / "Revise [current phase]" / "Stop here"
• Question loop — proposed answers as selectable options + "Other (I'll type)" escape hatch
• Confirmations — "Complete, move on" / "I want to add more"
• Classification — scope level, priority, any pick-one/pick-many decision

Always include an open-ended escape option. Multi-select when the question genuinely allows it. Fall back to conversational text only if no structured question tool is available in the IDE.

Warning Signs

• Skipped or careless research
• Guessed APIs off the map
• Staggered doc edits without a shared plan
• Polished paraphrase instead of user's intent
• Proceeding while user is unsure
• Tasks before accepted design
• Stale context-map.md
• Product code during planning

Verification

• Artifacts exist in the folder
• context-map.md matches research
• requirements.md holds intent in user's words, stories, and questions log
• design.md covers structure, flow, graph, and decisions — no uncertain language
• tasks.md has ordered tasks with acceptance criteria, grouping pass done
• Gates happened
• User has the folder path

Tone

Write like a clear human explaining to another practitioner. Apply human-techtalk.md rules to prose sentences (explanations, answers, status updates, headings) — never to artifact structure, templates, or formats. Keep RFC-style MUST / SHOULD / MUST NOT / MAY / CAN when obligation or permission must stay exact.