---
name: haoman-establish-coding-repo
description: >-
  Analyzes an existing Git repository locally, creates a reviewed Repository
  Evidence Brief without uploading raw source, attaches that brief to a Haoman
  Coding Repo Starter discussion, and establishes the confirmed Coding Repo
  Definition through an in-product edit proposal. Use when the current checkout has
  no matching Haoman Coding Repo or no accepted Coding Repo Definition, or when
  the user asks to attach, onboard, adopt, describe, or establish an existing
  codebase in Haoman. Requires Haoman MCP and a GitHub remote.
---

# Haoman establish Coding Repo

Establish one existing repository from local evidence. Local analysis describes
what exists; Haoman discussion decides what it means. Never promote code-derived
inference into canonical intent.

## Required tools

Require Haoman MCP tools:

- `list_projects`
- `list_coding_repos`
- `start_coding_repo_adoption`
- `attach_discussion_evidence`
- `continue_discussion`
- `complete_coding_repo_adoption`

If any is missing or unauthorized, stop. Ask the user to install or reconnect
the Haoman plugin and complete browser sign-in. Do not ask them to paste
credentials into chat. Never fall back to the legacy Project Identity
establishment flow.

## Workflow

```
Establish Coding Repo:
- [ ] 1. Resolve repository and target Project
- [ ] 2. Refresh local Haoman context cache
- [ ] 3. Analyze locally
- [ ] 4. Generate and review Repository Evidence Brief
- [ ] 5. Create adoption discussion and attach brief
- [ ] 6. Reconcile evidence in Haoman
- [ ] 7. Review and accept the in-product proposal
- [ ] 8. Verify accepted state
```

### 1. Resolve repository and target Project

1. Read the checkout's `origin` remote, default branch, and HEAD commit. Normalize
   HTTPS or SSH GitHub remotes to exact `owner/repo`.
2. Call `list_projects`, then `list_coding_repos` with `repoFullName`.
3. If exactly one Coding Repo matches, do not create another. Report it and use
   its existing founding/planning flow.
4. If several match, stop and surface the duplicates.
5. If none match, select the target Haoman Project from the user's words or ask
   one discriminating question. Never match a Project from repository name alone.
6. If `haoman/coding-repo-definition.md` already exists locally, treat it as
   repository evidence and ask whether the user intends to reconnect an
   existing Haoman record rather than found a new definition.

### 2. Refresh local Haoman context cache

After the target Project is known, follow `shared/context-cache.md`
(bundled with this skill):

1. Call `get_identity_documents` and `get_effective_operating_context`.
2. If a Coding Repo already matches this remote, also call
   `get_effective_technical_context` with that `codingRepoId`.
3. Compare hashes to `haoman/context/cache-manifest.json` and rewrite
   `.cursor/rules/haoman-context.mdc` plus `haoman/context/*` when stale or
   missing.
4. Use MCP for full Project identity while drafting evidence. Local cache is
   directional only.

If refresh tools fail, disclose the gap and continue local analysis only if the
user still wants the adoption flow.

### 3. Analyze locally

Remain read-only. Do not install dependencies, execute repository code, run
hooks, start services, or upload files.

Inspect only high-signal tracked material:

- README, product documentation, ADRs, and existing decision/PRD artifacts
- package/build manifests and lockfile names
- application entry points, routes, public interfaces, and configuration shape
- database schemas and migrations
- tests and deployment/operations configuration
- a bounded commit-history summary when useful, as secondary provenance rather
  than the lead of the analysis

Never read or transmit `.env*`, credentials, tokens, keys, certificates, personal
data exports, binary files, generated dependencies, build output, vendored code,
or unrelated files. Avoid source bodies when a manifest, test name, route name,
or schema declaration proves the same fact.

Classify every material claim:

- **Observed** — mechanically visible, with `path:line`; the appendix binds these
  citations to the analyzed HEAD. Put any specific commit-history references in
  the appendix as accounting notes.
- **Inferred — not yet confirmed** — a possible intention reconstructed from one
  or more cited observations.
- **Unknown or tension** — evidence is missing, conflicting, or may be obsolete.

Observed implementation proves what exists, not why it exists or whether it must
remain.

### 4. Generate and review the brief

Use [assets/repository-evidence-brief.md](assets/repository-evidence-brief.md) as
the exact structure. Create the working document in a temporary task directory;
do not add it to the repository or commit it.

Requirements:

- Title it `Repository Evidence Brief`.
- Lead with the project's content: product surfaces and behavior, architecture,
  data and integrations, and delivery characteristics. Do not open with Git,
  commit, generation, or inspection metadata.
- Record exact `owner/repo`, branch, HEAD commit, generation time, analysis scope,
  excluded categories, and skill name in the final evidence-accounting appendix.
- Keep Git history and commit details out of the main narrative. If bounded
  history materially explains the project, state the content-level observation
  in the main narrative and put its commit evidence in the appendix.
- Keep it under 40,000 characters.
- Include no fenced code blocks or raw source excerpts by default.
- Cite each material claim with local paths and line numbers where practical.
- Put all reconstructed purpose, commitments, and constraints under the inferred
  section, never under observed facts.
- Compute the final document SHA-256 and report it separately. Do not insert the
  digest into the document it hashes.

Show the user the complete brief or a faithful preview first, followed by its
evidence-accounting details:

- target Haoman Project;
- repository, branch, and commit;
- brief path and hash;
- categories inspected and excluded;
- an offer to open the complete brief when a preview was shown.

Ask explicitly whether to connect this repository and send this exact brief to
Haoman. This authorization covers internal Coding Repo creation and disclosure of
the reviewed brief only. It does not authorize accepting the resulting proposal.

### 5. Create discussion and attach the brief

Only after that confirmation:

1. Call `start_coding_repo_adoption` with the exact target Project and repository
   metadata. Do not send raw source. Keep the returned `codingRepoId` and
   `discussionId`.
2. Call `attach_discussion_evidence` with the discussion id, exact repository,
   HEAD commit, complete brief, its SHA-256, and `authorizationConfirmed: true`.
3. Materialize the returned document at `suggestedLocalPath` when provided.
4. Call `continue_discussion` once: ask Haoman to read the attached Repository
   Evidence Brief, state which evidence is available, and ask one discriminating
   question about what matches, what is accidental or obsolete, and what the
   founder wants the Coding Repo Definition to preserve. Follow
   `shared/discussion-turn.md` for the reply and any `savedDocuments`. Do not invent a Haoman reply on failure.
5. Materialize every `savedDocuments` entry from the tool result immediately.

The attachment is evidence with provenance `local_agent_observation`. It is not a
Coding Repo Definition and is never canonical.

### 6. Reconcile evidence in Haoman

Reuse the same discussion. Relay answers through `continue_discussion`, following
`shared/discussion-turn.md`, until Haoman saves a complete Coding Repo Definition.

- Confirm, correct, or reject inferred claims in conversation.
- Keep ordinary alignment quiet.
- Surface cited tensions without resolving them automatically.
- Treat Project Identity as inherited context, not repository-local truth.
- Never turn silence, repetition, or unrelated agreement into confirmation.

### 7. Review and accept the in-product proposal

When a complete Definition is saved:

1. Materialize and validate it.
2. Compute its SHA-256.
3. Show the complete proposed definition, whether it creates or replaces the
   accepted definition, and its definition hash.
4. Ask separately for explicit authorization to accept the proposal in Haoman.
5. Only after confirmation, call `complete_coding_repo_adoption` with that exact
   definition hash. No GitHub branch or pull request is created.

Never infer proposal acceptance from discussion activity or document generation.

### 8. Verify accepted state

Re-run matching and verify that Haoman exposes the authorized Definition hash as
the accepted Coding Repo Definition. Repository content remains evidence and is
not an acceptance gate. Only then hand back to Plan Then Build.

## Failure handling

- No GitHub remote: stop and ask which repository should be established.
- Sparse repository: produce a small brief with explicit unknowns; do not fill
  sections from guesswork.
- Sensitive evidence needed: describe the gap without uploading the sensitive
  content.
- HEAD changes before upload: regenerate the brief or bind it clearly to the old
  commit; never silently relabel it.
- Attachment or discussion failure: preserve the local brief and returned ids so
  the same adoption can resume without creating duplicates.
- Existing match under another Project: surface it; never create a duplicate.

## Anti-patterns

- Calling the brief a Project or Coding Repo Definition
- Uploading raw source, secrets, or an unreviewed document
- Server-side repository checkout
- Treating README claims or current dependencies as permanent commitments
- Creating a Coding Repo before disclosure confirmation
- Using one confirmation for both evidence upload and proposal acceptance
- Writing directly to the default branch