---
name: haoman-plan-then-build
description: >-
  Plans work through a Haoman Guided Prototype discussion via MCP, then loops
  until a buildable PRD is defined enough before implementing. Use when starting
  a feature, building something new, or when the user wants Haoman to shape the
  plan before code. Requires Haoman MCP.
---

# Haoman plan then build

Shape the work with Haoman Guided Prototype first. Do not implement until Haoman says the Prototype Definition is defined enough, unless the user explicitly overrides.

Haoman shapes; it does not gate. This skill constrains **your** build step. If the user says to build anyway, proceed and surface remaining gaps.

## Prerequisites

- Haoman MCP must be connected (tools like `list_projects`, `list_coding_repos`,
  `start_discussion`, and `continue_discussion`).
- After every `start_discussion` / `continue_discussion`, follow
  `shared/discussion-turn.md` (materialize `savedDocuments`, reuse `discussionId`).
- If MCP is missing, stop and ask the user to install or reconnect the Haoman
  plugin. If authorization fails, ask them to reconnect Haoman and complete the
  browser sign-in. Do not ask them to paste credentials into chat.

## Workflow

Copy and track:

```
Plan-then-build:
- [ ] 1. Resolve project
- [ ] 2. Refresh local Haoman context cache
- [ ] 3. Start Guided Prototype discussion
- [ ] 4. Planning loop (until READY_TO_BUILD: yes)
- [ ] 5. Pull definition artifacts
- [ ] 6. Implement
- [ ] 7. Conformance and discrepancy loop
```

### 1. Resolve project

1. Call `list_projects`.
2. If one project, use it. If several, ask which `projectId` (or match the name the user gave).
3. Do not invent identity; Haoman already injects it into the discussion.

#### Resolve the active Coding Repo

Plan Then Build is scoped to one repository, even when the selected Haoman Project owns several.
Resolve the current checkout's exact GitHub `owner/repo` from its remote, then call
`list_coding_repos` with that `repoFullName`. Match repository names
case-insensitively but never by a bare repository name alone.
If it cannot be resolved uniquely, ask which Coding Repo is active before classifying or persisting intent.
Never combine definition, PRD, amendment, conformance, or repository evidence from sibling Coding Repos.
The broader Haoman Project identity and Operating Model remain inherited context, not repo-local canonical truth.

#### Unmatched existing repository

When the exact remote has no Coding Repo match, do not treat it as greenfield and
do not silently select a similarly named Haoman Project. Offer:

> Haoman couldn't match this repository to a Coding Repo. I can inspect the
> codebase and draft a Coding Repo Definition, then open a Haoman discussion to
> review what appears true, what remains uncertain, and what may conflict with
> the selected Project Identity. Nothing will be connected, disclosed, or
> written until you confirm.

Then invoke `$haoman-establish-coding-repo`. That skill owns local analysis, the
reviewed Repository Evidence Brief, `attach_discussion_evidence`, reconciliation,
and the separately authorized in-product definition proposal. Resume Plan Then Build only
after it verifies the accepted definition. Do not reproduce a shorter adoption
flow inside this skill.

If `list_coding_repos` finds the remote under a different accessible Project,
surface that exact match instead of creating a duplicate. If any adoption tool
is missing, the connected Haoman MCP server is older than this workflow; stop
and ask the user to reconnect/update it rather than falling back to legacy
Project Identity establishment.

#### Historical intent (required when the repository has it)

Before planning, read the Haoman-accepted Coding Repo Definition, then inspect
`haoman/coding-repo-definition.md` and `haoman/prds/index.json` as repository
evidence. The accepted Haoman definition is authoritative; repository copies do
not silently replace it. Read the relevant indexed PRDs and any recorded
conformance result. If no accepted definition is available, say so and use
repository material only as attributed evidence.

Classify the requested work as `aligned`, `extension`, `tension`, or
`contradiction` before the planning loop. Stay quiet for ordinary aligned work.
Surface a tension or contradiction with exact Coding Repo Definition and prior-PRD citations;
an unconfirmed inference alone can never justify a definitive contradiction.

### 2. Refresh local Haoman context cache

After `projectId` and the active `codingRepoId` are resolved, follow
`shared/context-cache.md` (bundled with this skill):

1. Call `get_identity_documents` and `get_effective_operating_context`.
2. Call `get_effective_technical_context` with the explicit `codingRepoId`.
3. Compare hashes to `haoman/context/cache-manifest.json`. Rewrite
   `.cursor/rules/haoman-context.mdc` and `haoman/context/*` only when stale or
   missing.
4. Keep the MCP payloads for planning and build judgment. The mdc is compressed
   directional cache for the checkout, not a substitute for full doctrine.

If context tools fail, tell the user the build would be **unshaped by Operating
Model doctrine** (or technical context) and ask whether to continue. Never claim
the context was applied.

### 3. Start Guided Prototype discussion

Call `start_discussion`:

- `projectId`: from step 1
- `type`: `guided_prototype` (required — do not use `guided` for this skill)
- `title`: short label for the work (optional)
- `message`: the user's intent in their words, plus:

```text
We are planning work to implement after this discussion.
Stay in Guided Prototype planning mode. Do not write code.
Produce a buildable Prototype Definition (PRD + build plan) with no material ambiguity.
Define the product's intelligence before settling the mechanism. Capture what it
should quietly notice or learn, how it compounds from day 1 to day 30, what is
legible on demand, and what consequence boundary requires human authorization.
Require at least one felt-magic scenario that would fail if the intended
intelligence were absent.
Inspect for overloaded names, the same label used for distinct concepts or
contexts, and near-synonyms used for different things. Strongly recommend clear,
qualified terminology. Treat it as advisory unless a builder would have to guess
which route, file, schema field, interface, or user-facing concept is meant.
When I ask for a readiness check, answer with the READY_TO_BUILD block described below.
```

Keep the `discussionId` from the reply. Follow `shared/discussion-turn.md`
for replies and saved documents. Prefer that discussion for the rest of this skill.

### 4. Planning loop

Repeat until Haoman returns `READY_TO_BUILD: yes` (or the user overrides):

1. Relay Haoman's latest reply to the user in plain language. Ask them anything Haoman left open.
2. Send their answer (or your clarified synthesis) with `continue_discussion`, then
   follow `shared/discussion-turn.md`.
3. **Materialize saved notes locally** — whenever `start_discussion` / `continue_discussion` returns a non-empty `savedDocuments` array, immediately write each `content` to `suggestedLocalPath` (create parent dirs). Tell the user the path(s). Do not defer this to the end of planning. The Prototype Definition document is the primary build brief.
4. After a substantive exchange (or when the user asks to start building), send this readiness check via `continue_discussion`:

```text
Readiness check for implementation.

Is the Prototype Definition complete enough to hand to a coding agent with no material ambiguity?
(Product behavior, UX/interaction (entry points, journeys, screens, microcopy, feedback/empty/error recovery), exclusions, data model, interfaces, edge cases, todos, and verification must be decided. Material terminology ambiguity must be resolved. The intelligence model must also be behavioral and complete: experience principles, intelligence jobs/compounding, lifecycle, passive vs visible behavior, provenance/confidence/contradictions, autonomy/consequence boundaries, degradation, and at least one felt-magic evaluation scenario.)

Reply with exactly this block (fill it in), then any brief advice:

READY_TO_BUILD: yes|no
SUMMARY: <one paragraph of what to build>
MUST_HAVE:
- <concrete requirement from the PRD>
OUT_OF_SCOPE:
- <explicit exclusion from the PRD>
SUCCESS:
- <acceptance check from the PRD>
OPEN_GAPS:
- <blocking gap, or "none">
DEFINITION_PATH_HINT: <suggestedLocalPath of the latest Prototype Definition, or "pending">
```

5. Parse the block from the reply:
   - `READY_TO_BUILD: no` → tell the user the gaps, continue the loop. Do **not** implement.
   - `READY_TO_BUILD: yes` with empty or "none" gaps → go to step 5.
   - `READY_TO_BUILD: yes` but `OPEN_GAPS` still lists real gaps → treat as **no**; keep looping.
   - Missing or malformed block → ask Haoman once more to return only the block; if still missing, ask the user whether to continue planning or override.

6. Independently reject readiness when the saved definition lacks the
   intelligence-model sections or a scenario that would fail if the intended
   intelligence were absent, even if the response says `READY_TO_BUILD: yes`.
   Ask Haoman to repair the document and repeat the readiness check.
7. Call `check_prototype_readiness` for the selected saved document when the
   tool is available. Treat any returned gap as not ready; the conversational
   block and deterministic check must both pass.

Hard stop: do not edit application code for the planned feature while the loop is open.

### 5. Pull definition artifacts

1. Call `get_discussion` for the transcript if you need quotes.
2. Call `get_discussion_documents` with `includeContent: true` for any notes not already written locally; write missing ones to each `suggestedLocalPath`.
3. Re-verify `get_effective_operating_context` for the selected `projectId` against
   `haoman/context/effective-operating-context.json` / `cache-manifest.json`.
   If the returned `contentHash` matches, keep the snapshot; otherwise rewrite it
   and refresh `.cursor/rules/haoman-context.mdc` per `shared/context-cache.md`.
   - `attached: false` is a valid resolved state: state explicitly that the build
     is shaped by project identity only.
   - If the tool is missing, unauthorized, or fails, tell the user the build
     would be **unshaped by Operating Model doctrine** and ask whether to continue.
     Never claim the context was applied.
4. Re-verify `get_effective_technical_context` with the explicitly resolved active
   `codingRepoId` the same way for
   `haoman/context/effective-technical-context.json`. This repo-scoped bundle
   specializes the project doctrine; do not infer the repo from ambient state and
   do not silently fall back to the project context when the tool returns an
   explicit error.
5. Treat the latest local Prototype Definition under `haoman/discussions/<discussionId>/` as the authoritative build brief. Use Haoman's `SUMMARY` / `MUST_HAVE` / `OUT_OF_SCOPE` / `SUCCESS` as a short index into that document, not as a replacement for it.
6. Preserve the approved definition at a stable path under `haoman/prds/` and
   upsert `haoman/prds/index.json` with its path, definition hash, originating
   discussion, status, active Coding Repo id, and the Coding Repo Definition hash it was checked against.
   Publishing either file to a remote repository still requires explicit scoped
   authorization.

### 6. Implement

Only after step 4 passes (or explicit user override):

1. Implement against the Prototype Definition. Prefer small vertical slices that match its Build sequence and Todos.
2. Do not expand into Explicit exclusions / Scope boundary without a new Haoman turn.
3. Use Success signal, acceptance criteria, and Verification plan as done-checks.
4. If mid-build you discover a definition or scope conflict, pause, `continue_discussion` with the conflict, and wait for an updated readiness check before continuing large changes.
   If resolving it changes durable repo intent, open a Coding Repo Definition
   discussion and generate an in-product edit proposal. Accept it only with
   explicit authorization and preserve its rationale and source PRD in history.
5. If work surfaces a doctrine-versus-core/vertical tension, call
   `record_operating_model_conflict` with the selected project, cited tenet,
   identity layer, and current client surface. Surface it and continue; the
   record is persistence, not a gate.

### 7. Conformance and discrepancy loop

After implementation, do not stop at tests passing:

1. Read the exact launched Prototype Definition again. Map the implementation
   and test evidence to every acceptance criterion, explicit exclusion, and
   felt-magic scenario.
2. Produce an **agent draft** verdict for each line:
   `met`, `deviated`, `not_built`, or `added_not_in_spec`, with concrete
   evidence. Agent drafts never become founder-authoritative merely because the
   agent reported them.
3. Resolve from available evidence first: diff, tests, screenshots, runtime
   behavior, prior corrections, and discussion context. If one material point
   remains ambiguous, ask one discriminating question in the same discussion;
   do not create an approval checklist or repeat an ignored question without
   new evidence.
4. Send the draft conformance map and discrepancies to the same
   `discussionId` with `continue_discussion`. Ask Haoman to distinguish:
   definition gap, instruction/handoff loss, implementation deviation, or
   engineering-complete but intelligence-absent.
5. Materialize any returned `savedDocuments` immediately. If the definition or
   implementation changes, keep the same discussion, update the same build
   scope, and repeat conformance until discrepancies are resolved or explicitly
   retained by the founder.
   Update the PRD ledger with the implementation reference and conformance result;
   do not overwrite or discard the historical PRD.
6. Ordinary reversible confirmation may be expressed naturally and scoped in
   discussion. Never infer authorization from silence, lack of objection,
   unrelated agreement, or assistant repetition. Canonical, external,
   destructive, or irreversible action requires unambiguous scope-specific
   human authorization.

## Override

If the user explicitly says to build without waiting for Haoman:

1. Call `continue_discussion` once noting they chose to proceed with open gaps (if any).
2. Implement.
3. In your reply, list what remained undefined.

## Tool cheatsheet

| Tool | When |
|------|------|
| `list_projects` | Pick `projectId` |
| `list_coding_repos` | Match the checkout's exact GitHub remote to one Coding Repo |
| `start_coding_repo_adoption` | After confirmation, create a draft existing-repo record and evidence-led founding discussion |
| `attach_discussion_evidence` | Attach the reviewed, hash-verified local Repository Evidence Brief |
| `complete_coding_repo_adoption` | After separate exact authorization, accept the in-product Coding Repo Definition proposal |
| `start_discussion` | `type: "guided_prototype"`, first planning message |
| `continue_discussion` | Every planning turn and readiness check |
| `get_discussion` | Need full transcript |
| `get_discussion_documents` | Saved Prototype Definition / artifacts |
| `get_identity_documents` | Optional local identity read |
| `get_effective_operating_context` | Mandatory resolved doctrine snapshot before implementation |
| `get_effective_technical_context` | Mandatory repo-scoped doctrine snapshot for the selected Coding Repo |
| `record_operating_model_conflict` | Persist a surfaced cross-client doctrine/identity tension |
| `check_prototype_readiness` | Deterministic intelligence-aware readiness and conformance claims |

## Anti-patterns

- Starting implementation during the planning loop
- Skipping the readiness check because the plan "feels" clear
- Using `type: "guided"` instead of `guided_prototype`
- Treating Haoman advisory identity notes as a veto (surface them; do not invent a gate)
- Creating a new discussion every turn (reuse `discussionId`)
- Inventing a Haoman reply when a turn errors or times out
- Inventing discussion types not returned by `list_discussion_types`
- Leaving `savedDocuments` only in the MCP reply — write them to disk when they appear
- Implementing from the READY_TO_BUILD summary alone while ignoring the saved Prototype Definition
- Planning without resolving one active Coding Repo and reading its accepted Coding Repo Definition and relevant PRD history
- Treating an unmatched existing repository as greenfield or reviving the legacy Project Identity form
- Sending raw source, secrets, or an unreviewed evidence dump to Haoman
- Treating observed implementation as durable intent without founder confirmation
- Connecting a repository or accepting its definition proposal from the user's silence or from the initial adoption confirmation
- Mixing historical intent or citations across sibling Coding Repos
- Silently changing the Coding Repo Definition because a new feature creates tension
- Treating an unconfirmed inferred intention as a definitive contradiction
- Treating an engineering-complete CRUD result as conformant when the felt-magic scenarios fail
- Calling the removed `get_build_conformance` tool instead of reviewing conformance in the discussion
- Letting an agent self-report close conformance without founder evidence or verdict
- Turning discrepancy review into an approval inbox instead of evidence-first discussion