deep-plan

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Deep Plan — Research-First PRD Generation

Create execution-ready PRDs with full HQ context awareness, parallel research subagents, and a structured three-tier deep interview. Use this skill when the project is large, strategically important, touches unfamiliar code, or warrants the 10-15 minute upfront cost. For small ideas, tweaks, or fast captures, use the lightweight `/prd` skill instead.

**Important:** Do NOT implement. Just create the PRD.


## Work Mesh Live — trusted bind (do this first)

After Step 0 resolves `{co}` and before any other tool call that touches project work, bind the session per
`.claude/skills/_shared/work-mesh-live-bind.md` (US-011):

```bash
bash core/scripts/work-mesh-live-bind-trusted.sh \
  --company "{co}" --project "{project}" --task "{task}"
```

Omit `--task` when unknown. This writes `workspace/sessions/<sid>/meta.yaml`
and reconciles with `observation.trustedContext` (no `--trusted` CLI flag).

## Step 0: Company Anchor (from user input)

Resolve the company with the shared resolver — never by hand, and never from the first word alone:

```bash
bash core/scripts/resolve-company.sh --prompt "{the user's full input}"
```

It returns `{"company":"<slug>","source":"prompt|session|device_default|none"}`: an explicit whole-token slug in the input wins, then the bound session company, then the enabled device default. A session company always wins over the default; disabled and `needsChoice` defaults resolve as `none`. If `source` is `none`, use the structured picker before creating project files.

**If `company` is non-empty:** Read `companies/manifest.yaml` for company metadata, then:

1. **Set `{co}`** = resolved slug for the entire flow. Strip it from the description only when it was the leading token
2. **Announce:** "Anchored on **{co}**"
3. **Bind the session** — run `bash core/scripts/work-mesh-live-bind-trusted.sh --company "{co}"` now, before any read under `companies/{co}/`. The scope guard blocks company paths until the session is bound to `{co}`.
4. **Load policies (frontmatter-only)** — Collect eligible files for the resolved company, except `example-policy.md`, `README.md`, and `_digest.md`; preserve their order and split the stable file order into consecutive chunks of at most 40 files. For each chunk, run `bash core/scripts/read-policy-frontmatter.sh {file1} {file2} ...` once with each path as a separate argument. Keep each call under 30 KB of output. The first output block belongs to the chunk’s first file argument; each later block belongs to the path named by its preceding `# --- policy-file: <path> ---` separator. Note `enforcement: hard` titles. For hard-enforcement policies only, additionally read the `## Rule` section with a targeted range. Policy digests remain retired; SessionStart injects matching policies via `inject-policy-on-trigger`. Apply hard rules as constraints throughout the PRD
5. **Scope qmd searches** — If company has `qmd_collections` in manifest, use `-c {collection}` for all `qmd` calls
6. **Pre-load repos** — Extract `{co}.repos[]` from manifest. Present as repo options in the Architecture tier repo question
7. **Scope workers** — Filter to company workers (`companies/{co}/workers/`) + public workers (`core/workers/public/`)
8. **Scope projects** — Only search `companies/{co}/projects/` for existing project collision check

**If `source` is `none`** — do not silently assume personal scope. Ask the user which company this belongs to, or whether it is personal/HQ work, before creating any project files. The full input text is the project description either way.

## Step 1: Get Project Description

If user provided input, use as starting point.
If empty, ask the user: "Describe what you want to build or accomplish." Wait for response.

## Step 2: Scan HQ Context

Before asking questions, explore HQ. Resolve `mode` from Step 0 + input:

- **company mode** — a company slug was anchored in Step 0
- **repo mode** — no company anchor but a target repo is mentioned or resolvable from input
- **personal/HQ mode** — neither of the above (personal projects, HQ infrastructure work)

If `{co}` is anchored, scope all searches to that company.

**Companies & Context (only if `mode in (company, repo)`):**
- Read `agents-companies.md` (roles, priorities, three-tier roster) — needed to route cross-company PRDs
- Read `companies/manifest.yaml` (companies already listed there — never Glob for company discovery)
- **Skip both if already anchored in Step 0**: Step 0 already loaded manifest and matched the company. Re-reading is pure waste
- **Skip entirely for personal/HQ mode**: no company routing needed, no repo to map

**Workers (only if `mode in (company, repo)` AND the description plausibly needs a worker — otherwise skip):**
- Read `core/workers/registry.yaml` (workers already indexed there — never Glob for worker discovery). Skip if the description is clearly code/infra work not matching a worker skill
- If anchored: filter to company workers (`companies/{co}/workers/`) + public workers (`core/workers/public/`)
- **Skip entirely for personal/HQ mode**

**Existing Projects:**
- If anchored: `qmd search "prd.json" --json -n 20 -c {co}` (scoped) or search `companies/{co}/projects/` directly
- If not anchored: `qmd search "prd.json" --json -n 20` — existing projects across all companies and personal

**Knowledge (use single qmd hybrid query, not Grep, not vsearch+search pair):**
- If anchored + company has `qmd_collections`: `qmd query "<description keywords>" -c {collection} --json -n 10`
- If not anchored: `qmd query "<description keywords>" --json -n 10` — hybrid BM25 + vector + re-ranking for related knowledge, prior work, workers

**Company Policies (anchored only):**
- Already loaded in Step 0 (frontmatter-only). Do NOT re-read here. Note constraints from that scan

**Repo Policies (if repo resolved):**
- If target repo identified, list files in `{repoPath}/.claude/policies/` (if the directory exists; skip `README.md` and `_digest.md`), preserve their order, and split the stable file order into consecutive chunks of at most 40 files. For each chunk, run `bash core/scripts/read-policy-frontmatter.sh {file1} {file2} ...` once with each path as a separate argument. Keep each call under 30 KB of output. The first output block belongs to the chunk’s first file argument; each later block belongs to the path named by its preceding `# --- policy-file: <path> ---` separator. Do not prefer a digest file (retired). For hard-enforcement policies, additionally read the `## Rule` section

**Target Repo (if repo specified or discovered):**
- If anchored: company repos already pre-loaded from manifest. Present as options
- If target repo has a qmd collection (e.g. `my-app`): `qmd query "<description keywords>" -c {collection} --json -n 10` — hybrid search for related code, patterns, existing implementations
- Present: "Found related code: {list of relevant files}"

Present:
```
Scanned HQ:
- Mode: {company | repo | personal/HQ}
- Company: {co} (anchored) | TBD | n/a
- Workers: {relevant list or "skipped"}
- Existing projects: {list or "none matching"}
- Relevant knowledge: {if any}
- Policies: {count loaded, or "none"}
- Category: [company-specific | cross-company | personal | HQ infrastructure]
```

## Step 2.5: Infrastructure Pre-Check

Before generating the PRD, verify infrastructure exists for the target company/repo:

1. **Company**: If project targets a company, read `companies/manifest.yaml`. If company has `knowledge: null`, flag that it has no knowledge directory. If the user wants one, create `companies/{co}/knowledge/` as a plain real directory (never initialize Git or symlink it), add a README if useful, and update the manifest `knowledge` field with that directory path.

2. **Repo**: If `repoPath` specified and doesn't exist locally, flag: "Repo not found at {path}. Clone it or create new?" Add to `manifest.yaml` if missing.

3. **qmd collection**: If company has `qmd_collections: []` in manifest, flag and offer to create collection.

Fix any gaps before proceeding.

## Step 3: Get + Validate Project Name

Ask the user for project slug (or infer from description). Then:
1. If `{co}` already set by Step 0: use it directly (skip company detection)
   If NOT set: determine company from context (infer from description, repo, or ask the user)
2. Check if `companies/{co}/projects/{name}/` exists (also check `personal/projects/{name}/` for personal/HQ)
   - If exists: ask the user "Project exists. Continue editing or choose different name?"

From indigoai-us/hq-pack-core-skills, MIT.

More from indigoai-us/hq-pack-core-skills