# machine-discovery

Claude Code plugin for F1 Discovery workflows. It uses the shared project input registry under `docs/inputs/<project-slug>/` and creates Discovery artifacts under `docs/discovery/<project-slug>/`.

## Commands

- **`/machine-discovery:discovery-init <project-slug>`** - Creates the Discovery workspace, ensures the shared input registry exists, and copies `docs/business/<project-slug>/proposal.md` into `docs/discovery/<project-slug>/inputs/business-proposal.md` when available. Skill: [`skills/discovery-init`](skills/discovery-init/SKILL.md).
- **`/machine-discovery:process-input <project-slug> [files]`** - Transcribes audio through the `free-whisper` MCP, writes one resource `.md` per input under `docs/inputs/<project-slug>/transcriptions/`, and updates the shared input index. Skill: [`skills/process-input`](skills/process-input/SKILL.md).
- **`/machine-discovery:setup-token [token]`** - Saves your `free-whisper` API token into the global `~/.claude/settings.json` so transcription can authenticate (shared with machine-business). Skill: [`skills/setup-token`](skills/setup-token/SKILL.md).
- **`/machine-discovery:requirements <project-slug>`** - Extracts RF/RNF from the Discovery business proposal and ready shared inputs, writing item requirement files plus `requirements/index.json` and consolidated `requirements/requirements.md`. Skill: [`skills/requirements`](skills/requirements/SKILL.md).
- **`/machine-discovery:hla <project-slug>`** - Produces a high-level architecture from proposal and requirements. Skill: [`skills/hla`](skills/hla/SKILL.md).
- **`/machine-discovery:planning <project-slug>`** - Produces the F2 phase plan and milestones. Skill: [`skills/planning`](skills/planning/SKILL.md).
- **`/machine-discovery:draft-prds <project-slug>`** - Produces draft PRDs associated with RF lists under `draft-prds/items/` and maintains `draft-prds/index.json`. Skill: [`skills/draft-prds`](skills/draft-prds/SKILL.md).
- **`/machine-discovery:project-doc <project-slug>`** - Produces the F1 project document. Skill: [`skills/project-doc`](skills/project-doc/SKILL.md).
- **`/machine-discovery:commercial-offer <project-slug>`** - Produces the F2 commercial offer. Skill: [`skills/commercial-offer`](skills/commercial-offer/SKILL.md).
- **`/machine-discovery:render-docx <path.md>`** - Renders only the Project Document or Commercial Offer Markdown to DOCX. Skill: [`skills/render-docx`](skills/render-docx/SKILL.md).

## Workflow

```text
/machine-discovery:discovery-init acme-demo
  -> docs/inputs/acme-demo/{raw,transcriptions}/
  -> docs/inputs/acme-demo/index.json
  -> docs/discovery/acme-demo/inputs/business-proposal.md

Put more raw audio/text files in:
  docs/inputs/acme-demo/raw/

/machine-discovery:process-input acme-demo
  -> docs/inputs/acme-demo/transcriptions/<resource-slug>.md
  -> docs/inputs/acme-demo/index.json

/machine-discovery:requirements acme-demo
  -> docs/discovery/acme-demo/requirements/index.json
  -> docs/discovery/acme-demo/requirements/requirements.md
  -> docs/discovery/acme-demo/requirements/items/RF-001.md
  -> docs/discovery/acme-demo/requirements/items/RNF-001.md

/machine-discovery:hla acme-demo
/machine-discovery:planning acme-demo
/machine-discovery:draft-prds acme-demo
  -> docs/discovery/acme-demo/draft-prds/index.json
  -> docs/discovery/acme-demo/draft-prds/items/PRD-001.md
/machine-discovery:project-doc acme-demo
/machine-discovery:commercial-offer acme-demo
/machine-discovery:render-docx docs/discovery/acme-demo/project-doc/project.md
/machine-discovery:render-docx docs/discovery/acme-demo/commercial-offer/commercial-offer.md
```

Only the Project Document and Commercial Offer render to DOCX. Requirements, HLA, planning, and draft PRDs still use `.blocks -> .md`, but they are source artifacts grouped into `project-doc/project.md` instead of rendered separately.

## Input Contracts

Shared project inputs live in `docs/inputs/<project-slug>/index.json`:

```json
{
  "project": "acme-demo",
  "inputs": [
    {
      "src": "raw/notas.md",
      "md": "transcriptions/notas.md",
      "status": "ready"
    }
  ]
}
```

Discovery proposal input lives at:

```text
docs/discovery/<project-slug>/inputs/business-proposal.md
```

If `docs/business/<project-slug>/proposal.md` exists during init, it is copied there. If not, the user can place a business proposal manually at that path.

## Deterministic assembly

Discovery document skills MUST write a temporary `.blocks` content file and run:

```bash
bash plugins/machine-discovery/scripts/assemble-doc.sh <template.md.tmpl> <blocks-file> <output.md>
```

The AI MUST NOT hand-write final Markdown artifacts when a template exists.

## Setup - MCP `free-whisper`

The `process-input` skill transcribes audio through the `@the-ai-machine/free-whisper-mcp@latest` MCP server declared in [`.mcp.json`](.mcp.json). The API URL is **hardcoded and public** (`https://api.transcribe.skillbase.yareytech.com`); you only provide your **token**.

The `.mcp.json` references the token as `${FREE_WHISPER_API_TOKEN}`. The value lives in your **global** Claude Code config (`~/.claude/settings.json`, `env` block), so it survives plugin updates and is shared by `machine-discovery` and `machine-business`.

### Configure your token

1. **Generate / copy your token** at https://transcribe.skillbase.yareytech.com
2. **Save it**: run `/machine-discovery:setup-token <token>` (or run it without the token and paste it when asked). This writes `FREE_WHISPER_API_TOKEN` into `~/.claude/settings.json`, merging without touching your other settings.
3. **Reconnect the MCP**: run `/mcp`, select `free-whisper`, and reconnect. Reconnecting reloads its env; without this step you get **401**.

Verify with `/mcp` that `free-whisper` shows as *connected*.

> The token is a per-user secret: it MUST NOT be committed or placed in `.mcp.json`. Only the `${FREE_WHISPER_API_TOKEN}` reference lives in the repo; the value stays in your global config. If that variable is unset (you have not run `setup-token`, or saved it but did not reconnect), Claude Code cannot expand it and free-whisper returns 401.