@punks/cli 1.0.7 → 2.0.0-beta.0

package/dist/skills/agnostic/research/review-phase/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: review-phase
+description: Run a findings-first readonly review phase with explicit entry gates, delegated lenses, artifacts, and validation. Use for review-only goals, manual reviews, PRs, merged branches, external edits, suspicious code, or as the mandatory review wrapper inside delivery-phase.
+---
+
+# Review Phase
+
+A phase is a wrapper skill: it defines when to enter, when to stop, which inner
+skills to delegate to, what artifacts to produce, and which gates must pass.
+`review-phase` is standalone and readonly by default. Inside `delivery-phase`, it
+is mandatory and may hand findings back to delivery for fixes, debugging, docs,
+or validation because delivery owns completion.
+
+## Use When
+
+- The user asks for a review, audit, second pass, PR review, suspicious-code check, or review-only goal.
+- Code changed outside this session and needs independent inspection.
+- A branch was merged, rebased, generated, or edited externally and needs confirmation.
+- `delivery-phase` reaches its mandatory review gate.
+- The desired output is findings, risks, missing tests, or recommended next actions.
+
+## Do Not Use When
+
+- The user asks directly for implementation with no review gate.
+- The task is pure planning, requirements grilling, or docs writing with no artifact to review.
+- You need to edit code immediately; ask for or enter an owning delivery/debug/fix phase instead.
+- The review target is undefined and cannot be inferred from branch, diff, issue, PR, or user prompt.
+
+## Entry Contract
+
+1. Identify the review target: diff, PR, branch range, files, spec, plan, docs, or runtime evidence.
+2. State scope and readonly posture. If scope is ambiguous, ask one clarifying question.
+3. Read local guidance in checked directories, especially relevant `AGENTS.md` files under apps, packages, docs, or nested ownership boundaries.
+4. Choose review lenses and say which are active.
+
+## Review Lenses
+
+- `parallel-research`: fan out independent readonly checks when scope can split by subsystem, risk, or hypothesis.
+- `simplify`: inspect clarity, overcomplexity, unnecessary abstraction, derivable state, naming, and scope creep.
+- `improve-codebase-architecture`: surface architectural friction, shallow modules, poor boundaries, and module-depth opportunities.
+- Scoped local guidance: apply applicable directory instructions, stack skills, runbooks, and ownership rules discovered in checked paths.
+
+Use only the lenses that fit the target. Do not perform ceremonial delegation when a local pass is faster and equally reliable.
+
+## Workflow
+
+1. Gather evidence:
+   - inspect status, diff/range/PR metadata, tests, docs, and relevant local instructions
+   - prefer primary artifacts over tracker summaries
+   - record exact files and commands consulted
+2. Split if useful:
+   - use `parallel-research` for independent readonly checks
+   - synthesize before reporting; disagreements need evidence, not vote counting
+3. Review findings-first:
+   - prioritize bugs, regressions, broken contracts, missing validation, unsafe assumptions, and user-facing risks
+   - include file and line references when available
+   - separate blocking findings from improvements and optional cleanup
+4. Apply clarity and architecture lenses:
+   - use `simplify` to flag unnecessary concepts or complexity
+   - use `improve-codebase-architecture` to flag deeper boundary opportunities, usually as follow-up RFC candidates
+5. Validate:
+   - run readonly checks that match the target when safe: tests, typecheck, lint, build, docs link checks, or focused smoke commands
+   - if a check cannot run, state why and the residual risk
+6. Stop:
+   - standalone mode stops after findings and recommended next actions
+   - delivery mode returns findings to `delivery-phase`; delivery decides and performs fixes/debug/docs/validation
+
+## Output Contract
+
+Lead with findings, ordered by severity. For each finding include:
+
+- severity
+- file/line or artifact reference
+- issue and impact
+- evidence
+- recommended action
+
+Then include:
+
+- open questions or assumptions
+- validation run and result
+- short summary only after findings
+- whether this was standalone readonly review or delivery-owned review
+
+If there are no findings, say so clearly and still report validation coverage and residual risk.
+
+## Expected Outputs
+
+- Review report in conversation, issue, PR comment, or handoff artifact as requested.
+- Optional follow-up issue/RFC candidates for architectural opportunities.
+- In delivery mode only: fix/debug/docs tasks handed back to the owning phase.
+
+## Gotchas
+
+- Findings-first means do not bury issues under summary prose.
+- Do not edit code in standalone mode unless the user explicitly asks after seeing the review scope.
+- Do not use `simplify` as permission to refactor; report simplification opportunities unless delivery owns fixes.
+- Do not flatten scoped `AGENTS.md` guidance into generic advice; quote the concrete constraint that matters.
+- Do not let `delivery-phase` skip this phase just because tests passed.

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@punks/cli",
-  "version": "1.0.7",
+  "version": "2.0.0-beta.0",
   "description": "Devpunks AI scaffolding CLI",
-  "type": "module",
   "bin": {
     "devpunks": "dist/index.js",
     "dp": "dist/index.js",
@@ -10,9 +9,10 @@
   },
   "files": [
     "dist",
-    "docs",
+    "README.md",
     "AGENTS.md"
   ],
+  "type": "module",
   "scripts": {
     "build": "node ./scripts/build-dist.mjs",
     "baseline:build": "bun ./scripts/build-baseline.mjs",
@@ -25,13 +25,22 @@
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
+    "@effect/cli": "catalog:",
+    "@effect/platform": "catalog:",
+    "@effect/platform-bun": "catalog:",
+    "@effect/printer": "catalog:",
+    "@effect/printer-ansi": "catalog:",
+    "@punks/contract": "workspace:*",
+    "@punks/scaffold": "workspace:*",
+    "diff": "catalog:",
+    "effect": "catalog:",
     "react-devtools-core": "^6.1.5"
   },
   "devDependencies": {
-    "@effect/vitest": "0.27.0",
-    "@types/node": "^22.13.14",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   },
   "packageManager": "bun@1.3.5"
 }

package/dist/skills/agnostic/docs/docs-maintenance/SKILL.md

@@ -1,193 +0,0 @@
----
-name: docs-maintenance
-description: "Ingest a spec folder into the wiki domain layer by extracting and writing flow pages first, then concept pages, then syncing ingest metadata. Secondary: update docs/ when code changes alter architecture, setup, contracts, or operator workflow. Use when a spec is ready to be captured as domain knowledge after review or implementation, or when a code task changes non-obvious behavior that docs/ should reflect."
----
-
-# Docs Maintenance
-
-## Contract
-
-- **Role:** higher-order ingest and repo-docs orchestrator
-- **Entrypoint type:** public entrypoint
-- **Upstream:** reviewed or implemented spec folder, or code changes that may require `docs/` updates
-- **Delegates to:** internal flow-writing phase, then internal concept-writing phase
-- **Downstream:** synced wiki indexes, ingest metadata, wiki log, and any required `docs/` updates
-- **Entry conditions:** resolved spec folder for ingest work, or a concrete docs-affecting code change
-- **Stop conditions:** ingest bookkeeping complete, required docs updates complete, failures reported honestly
-
-## Overview
-
-**Primary purpose:** synthesize `<wiki-root>/specs/<domain>/<spec>/SPEC.md` (and optionally `IMPLEMENTATION-NOTES.md`) into the wiki domain knowledge layer. Write flow pages first, then concept pages, then sync ingest bookkeeping.
-
-**Secondary purpose:** keep `docs/` accurate when code changes alter architecture, setup, contracts, decisions, or operator-facing behavior.
-
-Read `<wiki-root>/AGENTS.md` before touching any wiki content.
-
-`<wiki-root>` is repo-shape dependent:
-- monorepo: `apps/wiki`
-- single-repo: `wiki`
-
----
-
-## Primary: Wiki Ingest Orchestration
-
-### Pipeline
-
-```
-docs-maintenance (orchestrator)
-  └─ 1. flow-writing phase    — writes flows/, updates domain index
-  └─ 2. concept-writing phase — reads flows/ for cross-linking, writes concepts/, updates domain index
-```
-
-**Why this order is required:** concept writing reads existing flow pages to cross-link concepts. Flow pages must exist before concept pages are written.
-
-### Inputs
-
-Accept any of:
-- A spec folder path: `<wiki-root>/specs/<domain>/<spec>/`
-- A domain name + spec name
-- An explicit `SPEC.md` path
-
-Resolve all inputs to a full spec folder path before continuing. If the target is still ambiguous, ask only for the missing folder.
-
-### Step 1: Guard
-
-Check `SPEC.md` frontmatter for `ingested: true`. If set, exit with a clear no-op message.
-
-Verify the spec has `domain:` in frontmatter. Error if absent.
-
-### Step 2: Read the source
-
-Read in order:
-1. `SPEC.md` — mandatory. If missing, stop and report.
-2. `IMPLEMENTATION-NOTES.md` — optional. If present, flows and concepts become `status: implemented`. If absent, status is `proposed`.
-   - Check its frontmatter. If it lacks frontmatter (no YAML block), add it now before continuing:
-     ```yaml
-     ---
-     domain: <domain from SPEC.md>
-     type: implementation-notes
-     spec: <spec id from SPEC.md>
-     links:
-       - "[[specs/<domain>/<spec>/SPEC]]"
-     ingested: false
-     last_ingested: null
-     created: <today>
-     updated: <today>
-     ---
-     ```
-
-Verify `<wiki-root>/domains/<domain>/` exists with a `<domain>.md` index file. If the domain is missing, stop and scaffold the wiki/domain structure first.
-
-### Step 3: Extract flows
-
-A flow exists when the spec describes a **sequence of user or system actions with a defined start, steps, and end outcome**.
-
-Look for flows in:
-- Multi-step acceptance criteria (e.g. "On save, the system runs duplicate detection → blocks if exact match → redirects operator on success")
-- Explicit user journeys or process descriptions in the Context section
-- "When X, then Y" conditional chains across multiple acceptance criteria
-- Any section titled Flow, Process, Journey, or similar
-
-For each flow found:
-- Assign a descriptive `flow_name` (e.g., "Create Patient", "Document Upload", "Duplicate Check")
-- Extract `flow_content`: triggering event, actors involved, ordered steps with decision points, terminal outcome
-- When `IMPLEMENTATION-NOTES.md` is present: note deviations, surprises, or blocked steps inline
-
-If no multi-step sequence is discernible (e.g., a purely data-model spec), record the absence and skip flow delegation.
-
-### Step 4: Write flow pages
-
-Read [references/flow-pages.md](references/flow-pages.md) and apply that contract to every extracted flow.
-
-Wait for all flow pages to complete before proceeding.
-
-If any flow write fails, stop immediately. Do not proceed to concept writing. Report the failure so the run can be resumed cleanly.
-
-### Step 5: Extract concepts
-
-A concept exists when the spec **names a domain entity or term with defined attributes, invariants, or bounded scope**.
-
-Look for concepts in:
-- Fields listed in acceptance criteria (e.g., `first_name`, `email`, `acquisition_channel`, `nin`)
-- Explicit data model or entity sections
-- Nouns that recur across multiple acceptance criteria with their own distinct attributes or rules
-- Enum sets representing a bounded domain state (e.g., `acquisition_channel` values)
-- Entities referenced via `[[wikilinks]]` to other specs or domain pages
-
-**Grouping rule:** collect related fields under one owning entity rather than creating a concept per field. All patient registry fields → one "Patient" concept. All acquisition channel variants → one "Acquisition Channel" concept.
-
-If no distinct domain entity is identifiable, record the absence and skip concept delegation.
-
-### Step 6: Write concept pages
-
-Read [references/concept-pages.md](references/concept-pages.md) and apply that contract to every extracted concept.
-
-Wait for all concept pages to complete.
-
-### Step 7: Mark sources as ingested
-
-Update `SPEC.md` frontmatter:
-```yaml
-ingested: true
-last_ingested: YYYY-MM-DD
-```
-
-If `IMPLEMENTATION-NOTES.md` is present, update its frontmatter:
-```yaml
-ingested: true
-last_ingested: YYYY-MM-DD
-```
-
-Also populate its `links` array with every flow and concept page written in Steps 4 and 6 (in addition to the SPEC link that was set in Step 2). This is the only moment where IMPLEMENTATION-NOTES links are updated — do not leave them pointing only at the SPEC.
-
-### Step 8: Log entry
-
-Append to `<wiki-root>/log.md` (cap at 50 entries; drop oldest when over):
-```md
-## [YYYY-MM-DD] ingest | <spec title>
-- Source: [[specs/<domain>/<spec>/SPEC]]
-- Flows written: <count>
-- Concepts written: <count>
-```
-
-### Step 9: Update wiki index
-
-If new pages were created, update the Concepts and Flows counts in the relevant Domains table row in `<wiki-root>/index.md`.
-
-### Resumability
-
-Output pages are the checkpoints. On re-invocation of the same source:
-
-- Flow pages with `ingested: true` → skip Step 4 for those flows
-- Any expected flow page missing → re-run Step 4 for it before Step 6
-- Concept pages with `ingested: true` → skip Step 6 for those concepts
-
----
-
-## Secondary: docs/ Maintenance
-
-Update `docs/` when a code task changes **architecture, setup, contracts, decisions, or non-obvious operator-facing behavior**. Do not let docs/ work displace or delay wiki ingest.
-
-1. Read `docs/README.md` and the nearest affected section README before editing.
-2. Prefer editing an existing leaf doc over creating a new one.
-3. When a doc is added, removed, or renamed: update `docs/README.md` and the nearest section README in the same task.
-4. Record repo-wide behavior changes in `docs/architecture/decisions/`.
-
-**Route by owned behavior:**
-- Backend/runtime surface → `docs/reference/domains/backend-effect-sql.md` or `docs/runbooks/`
-- Auth/user-management → `docs/reference/domains/user-management.md`
-- Frontend/app structure → `docs/reference/domains/frontend-application-structure.md`
-- AI workflow/agent infrastructure → `docs/runbooks/subagent-templates.md` or `docs/runbooks/claude-code-hooks.md`
-
----
-
-## Never Do
-
-- Ingest a spec with `ingested: true` — exit early instead
-- Ingest an `IMPLEMENTATION-NOTES.md` with `ingested: true` — treat it as already reflected in domain pages
-- Proceed to concept writing when a flow write has failed
-- Create `docs/prd`, `docs/dev`, roadmap, sprint, or backlog-mirror folders
-- Document speculative or future-state features as current truth
-- Put agent task instructions inside human-facing docs pages
-- Leave docs orphaned from `docs/README.md` after adding or renaming them
-- Duplicate content between `<wiki-root>/domains/` (the "what") and `docs/reference/domains/` (the "how")

package/dist/skills/agnostic/docs/docs-maintenance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Docs Maintenance"
-  short_description: "Wiki ingest plus repo docs maintenance"
-  default_prompt: "Use $docs-maintenance to own the wiki ingest pipeline, then keep docs/ human-facing and implementation-grounded when code changes affect durable knowledge."

package/docs/README.md

@@ -1,35 +0,0 @@
-# CLI Docs
-
-- [Requirements](./reference/dp-requirements.md)
-- [Scaffolding runbook](./runbooks/dp-cli-scaffolding.md)
-
-Domain knowledge:
-
-- [Wiki index](../wiki/index.md)
-
-The wiki is the durable domain layer for specs, raw inputs, flows, and concepts. Keep operator runbooks and implementation reference in `docs/`; keep stable product/domain knowledge in `wiki/`.
-
-Implementation notes:
-
-- canonical bundled scaffold metadata and shared assets live in `src/data/`
-- runtime scaffold content resolves from a `Baseline`: latest remote stable by default, bundled fallback when offline or forced with `--baseline bundled`
-- pack-owned lint asset metadata lives in `src/data/catalog/lint.ts`
-- distributed skill assets live in `skills/`
-- runtime projection/writing logic lives in `src/scaffold/`
-- `punks update` refreshes scaffold-managed assets from `.devpunks/scaffold-manifest.json`
-- CLI startup checks run in a detached advisory worker at most once per 12 hours by default. They check npm's `latest` dist-tag and whether the named `dp-cli` skill is present, but startup never installs or updates packages/skills while another CLI command is starting. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks, `DP_UPDATE_TAG=next` to compare against another dist-tag, and `DP_STARTUP_CHECK_INTERVAL_MS=0` to force the worker during local testing.
-- baseline releases use `baseline/stable/*` GitHub release tags, separate from npm executable tags such as `v1.0.1`
-- shared neutral hook and sync assets live in `src/data/hooks/` and `src/data/scripts/`; hook commands infer the target repo package manager from `packageManager` and lockfiles
-- scaffolded required tools always include `portless` and `skills` so generated guidance can standardize local dev origins and keep skill entrypoints up to date
-- `punks scaffold setup` checks the base required tools (`portless`, `skills`) before repo detection and checks selected-pack tools after pack confirmation.
-- Oxlint specs/starter config are scaffolded only when scanned manifests already declare `oxlint`; the auto format/lint hook is scaffolded only when manifests declare `oxfmt`. PR creation is not gated by a scaffolded test-suite hook. Other lint/format stacks are intentionally left untouched for now.
-- the default debug pack scaffolds the local `debug-agent` skill and installs/verifies the `debug-agent` CLI without running its agent-install wizard
-- scaffolded repos keep project-local skills in `.agents/skills/`; only `.claude/skills` is a compatibility symlink mirror
-- React scaffold surfaces include `async-react-patterns` alongside the existing React composition, structure, and Vercel guidance so agents avoid outdated manual async state patterns.
-- Next.js detection implies the React pack even when `react` / `react-dom` are not directly listed in scanned manifests.
-- Frontend surface detection scaffolds `frontend-domain-structure` with the frontend pack when React or Next.js is detected.
-- Backend surface detection scaffolds `backend-domain-structure`, `backend-recoverable-actions`, and `logging-best-practices` when backend framework/data/auth packages are detected, or when workspace names/paths clearly identify API, backend, server, or service packages. Workspace prompt specs apply backend packs only to backend-looking workspaces, not frontend workspaces that happen to share repo-level backend/data detections.
-- Drizzle detection selects the `drizzle` pack for data-layer prompt/lint metadata, but does not imply Effect skills or Effect opensrc references unless `effect` / `@effect/*` is also detected.
-- Scaffold no longer preselects concrete opensrc repositories. Post-scaffold agents must choose and clone the core detected libraries whose source behavior matters before authoring final prompts or plans.
-- The default subagent manifest includes a read-only `code-review` template that uses `simplify` and `improve-codebase-architecture`; root prompt guidance routes review requests to findings-first review before broad refactor planning.
-- Non-surface agnostic skill groups are mandatory scaffold packs (`debug`, `docs`, `planning`, `quality`, `research`, `requirements`, `subagents`); `frontend` and `backend` remain detection-driven.

package/docs/harness-intelligence-grill-log.md

@@ -1,39 +0,0 @@
-# Harness Intelligence Grill Log
-
-This log records locked requirements decisions for rethinking this repo as the Harness Intelligence project.
-
-## Initial Situation
-
-The repo currently provides real value as the `punks`/`dp` scaffolding CLI plus canonical scaffold baseline data. It has battle-tested workflow assets, repo-aware setup behavior, baseline publishing, and a local wiki-shaped knowledge tree.
-
-The repo does not yet provide the full product/distribution surface needed for wider colleague adoption or public company communication:
-
-- no Turborepo application layout
-- no public Fumadocs wiki/docs app
-- no public landing page
-- no Effect backend for scaffold distribution, validation, or future orchestration
-- no settled CLI-vs-backend boundary
-- no durable explanation of harness theory, criteria, trust model, and sales/marketing narrative
-
-## Branches
-
-### Branch A: Product Boundary
-
-Purpose: define what "Harness Intelligence" is as a product/system, and what this repo must own.
-
-### Branch B: Distribution Architecture
-
-Purpose: define Turborepo shape, app/package boundaries, backend role, CLI role, baseline/data flow, and public surfaces.
-
-### Branch C: Wiki and Theory
-
-Purpose: define the docs knowledge model, Fumadocs information architecture, and the harness engineering criteria currently living in the user's head.
-
-### Branch D: Trust and Adoption
-
-Purpose: define what colleagues need to trust the AI harness setup, how validation works, and what proof material must exist.
-
-### Branch E: Company Communication
-
-Purpose: define landing-page and sales narrative for how Devpunks engineers are AI-superpowered without becoming vague marketing copy.
-

package/docs/harness-intelligence-grill-status.md

@@ -1,25 +0,0 @@
-# Harness Intelligence Grill Status
-
-Current grill artifacts:
-
-- Log: `docs/harness-intelligence-grill-log.md`
-- Status: `docs/harness-intelligence-grill-status.md`
-
-## Branch Dashboard
-
-| Branch | Completion | Locked direction | Still open |
-| --- | ---: | --- | --- |
-| Product Boundary | 10% | Repo is being reconsidered as the Harness Intelligence project, not only a CLI package. | Canonical product definition, audience split, repo ownership boundary. |
-| Distribution Architecture | 10% | Target mentions Turborepo, public docs app, landing page, Effect backend, and CLI. | App/package boundaries, backend-vs-CLI responsibilities, data/source-of-truth flow. |
-| Wiki and Theory | 10% | Existing wiki shape exists locally; missing public Fumadocs app and full theory/criteria content. | IA, criteria taxonomy, private vs public knowledge split, docs ownership. |
-| Trust and Adoption | 10% | Colleague recognition/validation is a primary requirement. | Trust evidence, onboarding path, validation gates, adoption metrics. |
-| Company Communication | 10% | Public explanation must support sales/marketing around AI-superpowered developers. | Landing page promise, proof points, tone, relationship to devpunks.com. |
-
-## Parked Branches
-
-- None yet.
-
-## Current Question
-
-Q1: Product Boundary.
-

package/docs/reference/dp-requirements.md

@@ -1,225 +0,0 @@
-# `punks` Requirements
-
-This document captures the durable requirements agreed for the `punks` CLI so the implementation can evolve without losing the product contract.
-
-## Goal
-
-`punks` is an AI-first scaffolding CLI for agent-ready projects.
-
-It should:
-
-- scaffold the right AI operating context for the current project phase
-- keep pre-boilerplate flows lightweight and language-agnostic
-- keep repo-aware setup deterministic once a repo and stack exist
-- emit operator prompts that guide the next agent through the current gate
-
-## Core Principles
-
-- The lifecycle is explicit.
-- Pre-boilerplate scaffolding is stage-driven.
-- Repo-aware setup is pack-driven.
-- Skill selection is curated by the CLI, not exposed as a raw chooser.
-- Shared bundled assets come from this repo, not network fetches at runtime.
-
-## Command Contract
-
-`punks scaffold` is the lifecycle index. It explains the available scaffold phases and is no longer an alias for repo setup.
-
-The current scaffold namespace is:
-
-- `punks scaffold init`
-  requirements gate; scaffolds `requirements-grill`, `write-backlog`, and seeds the wiki tree
-- `punks scaffold backlog`
-  backlog gate; currently prints guidance only
-- `punks scaffold setup`
-  repo-aware setup; detects technologies, resolves packs, and emits prompts/manifests/hooks
-
-## Pre-Boilerplate Contract
-
-`punks scaffold init` and `punks scaffold backlog` assume the operator is already inside the target workspace or repository folder.
-
-They should:
-
-- copy only their exact stage-owned skills into `.agents/skills/`
-- overwrite those scaffolded files on rerun for idempotency
-- let `init` seed the dedicated wiki tree early so later planning/docs skills have a concrete schema root
-- avoid pack detection, stack evaluation, or other side effects beyond the minimal repo-shape sniff needed to choose `apps/wiki` vs `wiki`
-- print a fixed operator prompt to stdout that explains how to use the newly scaffolded skills
-- make the requirements grill the canonical gate before backlog creation, with `write-backlog` available after the grill handoff closes
-
-They should not:
-
-- write a root `AGENTS.md`
-- scan for PRDs yet
-- create issues, call external services, or mutate anything beyond the bundled scaffold files they own
-
-The dedicated wiki tree is part of that bundled stage output:
-
-- monorepo-shaped target => `apps/wiki/`
-- single-repo target => `wiki/`
-
-That wiki tree is not the same thing as `docs/`. It owns specs, raw inputs, and synthesized domain knowledge.
-
-## Repo-Aware Setup Contract
-
-`punks scaffold setup` remains the deterministic repo-aware scaffold flow.
-
-It should:
-
-- detect repo facts, not ask the agent to invent them
-- resolve those facts to predefined Devpunks packs
-- scaffold the shared AI setup
-- emit instructions/specs the next agent can use to generate repo-scoped prompts and subagent config
-
-The CLI must stay deterministic at the detection/mapping layer and flexible at the final repo-reconciliation layer.
-
-## Repository Model
-
-`punks scaffold setup` must support both:
-
-- monorepos
-- single-repo package layouts
-
-Repo shape remains an invariant used during scaffold generation and must stay overrideable with:
-
-- `auto`
-- `monorepo`
-- `single`
-
-## Detection Contract
-
-Initial setup detection is JS/TS manifest based.
-
-Primary sources:
-
-- repo `package.json` files discovered recursively, with ignore rules for generated/non-source trees
-
-Initial technology mapping:
-
-- `next` -> `nextjs`, `react`
-- `react`, `react-dom` -> `react`
-- `@tanstack/react-query` and related query packages -> `tanstack-query`
-- `elysia` -> `elysia`
-- `@trpc/*` -> `trpc`
-- `drizzle-orm`, `drizzle-kit` -> `drizzle`
-- `better-auth` -> `better-auth`
-- `turbo` -> `turborepo`
-- `effect`, `@effect/*` -> `effect`
-
-`drizzle` is data-layer detection only. It must not imply Effect skills or Effect source references unless the `effect` pack is selected independently.
-
-## Pack Contract
-
-Pack resolution happens at pack level only during `punks scaffold setup`.
-
-The CLI must never ask the user or agent to choose raw skills in the repo-aware setup flow.
-
-### Default packs
-
-Default packs are always preselected and visually distinguished. They are not removable.
-
-Current default packs:
-
-- `docs`
-  `docs-maintenance`
-- `planning`
-  `grill-me`, `create-spec`, `create-plan`, `implement-spec`
-- `subagents`
-  `domain-plan`, `domain-execute`, `parallel-task`, `swarm-planner`
-- `quality`
-  `tdd`, `simplify`
-- `research`
-  `parallel-research`
-- `requirements`
-  `requirements-grill`, `write-backlog`
-
-### Surface packs
-
-Frontend-oriented skills should be grouped into a single detected frontend surface pack:
-
-- `frontend`
-  `agent-browser`, `frontend-design`, `web-design-guidelines`
-
-Framework/data packs may layer on top of that surface:
-
-- `react`
-  `async-react-patterns`, `react-domain-structure`, `vercel-composition-patterns`, `vercel-react-best-practices`
-- `nextjs`
-  `next-best-practices`, `next-cache-components`
-- `tanstack-query`
-  `tanstack-query`
-
-Backend-oriented agnostic skills should be grouped into a single detected backend surface pack:
-
-- `backend`
-  `backend-domain-structure`, `backend-recoverable-actions`, `logging-best-practices`
-
-## Prompt Contract
-
-Pre-boilerplate commands use fixed stdout operator prompts.
-
-`punks scaffold setup` must not hardcode all final repo-scoped prompts as static bundled prompt bodies. Instead it should:
-
-- directly scaffold only shared global harness prompts
-- emit prompt specs for root/docs/workspace scopes
-- instruct the next agent how to turn those specs into final scoped `AGENTS.md` files
-
-## Subagent Manifest Contract
-
-`punks scaffold setup` must emit structured guidance for `.agents/subagents/manifest.mjs`.
-
-That guidance must let the next agent derive:
-
-- which specialists should exist
-- owned paths
-- guidance files
-- packs
-- explicit skills
-- scope boundaries
-
-It should also scaffold the neutral harness-sync layer around that manifest:
-
-- shared hooks under `.agents/hooks/`
-- harness sync entrypoint under `.agents/scripts/sync-subagents.mjs`
-- generated harness-native agent/config/mirror surfaces for `.claude`, `.codex`, `.cursor`, and `.opencode`
-
-## Tool Bootstrap Contract
-
-If a bundled skill or scaffold baseline depends on a global external tool, the CLI should model that dependency explicitly and ensure the tool is installed during `punks scaffold setup`.
-
-Current examples:
-
-- `agent-browser`
-- `opensrc`
-- `portless`
-
-The scaffold output should also record the resolved tool requirements in a machine-readable manifest.
-
-`punks scaffold setup` should check base required tools before repo detection so missing `skills` or `portless` is surfaced immediately. Tools required only by selected packs can be checked after pack confirmation.
-
-Scaffold output should not preselect concrete opensrc repositories. The generated post-scaffold instructions should require the next agent to identify the core detected libraries whose source behavior matters, ask the user when that set is ambiguous, and run `opensrc path <package>` or `opensrc path owner/repo` for only that focused set.
-
-## Lint Scaffold Contract
-
-The shipped starter/root lint baseline should exclude generated and non-source surfaces by default, including:
-
-- all lock files
-- all dot-directories
-- generated agent/harness folders unless a target repo explicitly opts them back into lint scope
-
-When scaffold guidance leads an agent to adopt Oxlint or Oxfmt, it must tell the agent to replace existing lint/format entrypoints deliberately: package scripts, task pipelines, CI, editor/docs references, and agent hooks should agree on the new tools.
-
-Until additional lint/format stacks are supported, repo-aware setup should emit Oxlint specs/starter config only when `oxlint` is declared in scanned package manifests and emit the Oxfmt/Oxlint format hook only when `oxfmt` is declared. Repos without those packages should get no lint/format scaffold surfaces.
-
-## Dedicated CLI Repo Contract
-
-The standalone private `wearedevpunks/cli` repo remains the source of truth for:
-
-- pack registry
-- stage-owned scaffold prompts
-- subagent templates
-- hook base files
-- root/shared prompt assets
-- examples
-
-The public `wearedevpunks/skills` repo remains the source of truth for the shareable skill directories. This private CLI syncs that public tree into local `skills/` through a local cache clone and scaffolds from the local copy. Runtime scaffold behavior must not depend on network fetches.