client-hq-feature-workflow

name: client-hq-feature-workflow description: >- Run a client-hq-specific discover/synthesize/adversarial-verify/draft workflow over a feature slice of client-hq, with the domain invariants (auth guard matrix, page-token scopes, action.js allowlist, RLS posture, Vercel deploy rails, gotcha library, verified file map) baked into every agent prompt. Use when the operator says "rip through X on client-hq", "what's broken in [page/pipeline]", "audit the [slice] in CHQ", "discover gaps in [area]", or wants a multi-agent sweep of any client-hq surface (admin page, client-facing template, api route family, cron pipeline, site-editor flow). Produces adversarially-verified gaps plus reviewed structured patches ready for the apply-reviewed-patches skill. Do NOT use for: a single-file fix, a one-line change, or work already fully scoped upfront (edit directly); other repos (engage uses engage-feature-workflow; site work uses the site skills); or applying/landing patches (that is apply-reviewed-patches).

Wraps the Workflow tool with client-hq domain knowledge so every run starts warm: verified file map (no cold grep), authority model (who can do what, enforced where), gotcha library (intentional weirdness never reported as gaps), adversarial three-lens verification (authority / ops-convention / reproduction), and patch drafting in the exact shape apply-reviewed-patches consumes. The workflow is strictly READ-ONLY; all writes happen later, under operator control.

Skill files (this directory):

workflow.js - the Workflow script (pass via scriptPath)
filemap.md - verified starting points, fed in via args.fileMap
authority.md - the authority model, fed in via args.authority
gotchas.md - the growable gotcha library, fed in via args.gotchas

Flow

1. Scope the slice

Extract the slice description from the trigger phrase ("the newsletter composer", "the booking flow", "client-editor auth", "the report pipeline"). If too vague to aim discovery agents (one sentence cannot say what surface is in scope), ask ONE clarifying question, then proceed.

2. Pre-flight (cheap, mandatory)

Read filemap.md, authority.md, and gotchas.md from this skill directory.
Verify every file-map path exists in one ls sweep against the repo root (default ~/Desktop/Moonraker/Biz/Dev/client-hq; git pull first). Drop dead paths from the map text you pass in and add a line per dead path to args.extraContext: "former location X no longer exists; find the new home as part of discovery". Update filemap.md afterward.
Check AGENT_LOG.md tail and gh pr list if the slice overlaps in-flight work: a recent session may already cover a gap.

3. Choose mode

Default: single-pass discovery, width 3. No flags needed.
Operator gave a token budget ("+600k"): width auto-scales in the script.
Trigger is audit-shaped ("what's broken in...", "audit...") AND a budget was given: set args.audit = true (loop-until-dry discovery).
Operator wants findings only, no patches: set args.draft = false.

4. Launch

Workflow({
  scriptPath: "<this skill dir>/workflow.js",
  args: {
    slice: "<slice description>",
    repoRoot: "<client-hq checkout>",
    fileMap: "<contents of filemap.md>",
    authority: "<contents of authority.md>",
    gotchas: "<contents of gotchas.md>",
    audit: <bool>, draft: <bool>,
    extraContext: "<dead-path notes, operator hints>"
  }
})

5. Read the result honestly

The return is { slice, codeable, rejected, confirmedUndrafted, unconfirmed, failures }.

failures first. Dropped finders are a COVERAGE GAP: name the angle that died and offer to re-run it as a fresh agent (known gotcha: schema weight makes agents emit prose and drop to null; resume caches errors, so re-run fresh, never resume).
Report to the operator: confirmed gaps (with severity), what was refuted and why (refutations are signal, often a gotcha doing its job), and what was rejected in review.
Save the full result JSON to a file in the project tree (not /tmp), e.g. client-hq/.tmp-agent-work/PATCHES-<slice>.json, so patch bodies never need transcription.

6. Land (separate, gated)

Hand the saved JSON to the apply-reviewed-patches skill. client-hq specifics it must respect:

Direct push to main is allowed BUT main auto-deploys production on Vercel with no staging. Treat every commit as a deploy: operator reviews the staged file list before commit, and verify the Vercel deployment status after push (silent ERROR state means nothing deployed; vercel.json is the most common cause).
count==1 guard per edit; sha-verify creates; --dry-run first.
Post-apply validation: node --check every touched .js; for inline scripts in touched HTML, extract and node --check them; em-dash scan on the staged diff (git diff --cached -U0 | grep '^+' | grep -P '\x{2014}' must be empty); staged file list printed for operator review before commit.
If a patch adds an entry to vercel.json functions, count entries: the hard limit is 50 and exceeding it breaks ALL deploys.

7. Promote gotchas (keeps the skill compounding)

Before closing out, ask: did this run surface (a) intentional weirdness an agent wrongly flagged, or (b) a constraint learned by failure? Append each to gotchas.md (one to three lines, correct section). If file locations moved, update filemap.md and its "last verified" date. If the auth surface changed (new guard, new token scope, new allowlist table), update authority.md. This step is why the skill beats plain repo access; do not skip it.

Known failure modes

Heavy output schemas kill structured output. The script's schemas are deliberately light; do not "improve" them with deep required nesting.
A transient 429 can kill a whole run. Re-launch FRESH (resume would cache the error as complete).
Subagents emit em-dashes. The review pass flags them, but the staged-diff scan in step 6 is the real gate.
Synthesis papers over dropped discovery slices. If failures shows drops, treat the synthesized gap list as incomplete, not wrong.
There is no local dev server and no test suite: "cannot run it" is not a finding, and patches cannot be runtime-verified before push. Static validation (node --check, careful reads) is the only pre-push gate.
Plain node --check workflow.js false-fails on the top-level return (legal in the Workflow runtime). Parse-check by wrapping: { echo 'async function _w(args, budget, agent, parallel, pipeline, phase, log) {'; sed 's/^export //' workflow.js; echo '}'; } > /tmp/wf.js && node --check /tmp/wf.js