@punks/cli 1.0.7 → 2.0.0-beta.1

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.1",
   "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",
@@ -21,17 +21,27 @@
     "dev": "bun run ./src/index.ts scaffold",
     "local": "bun run build && bun run ./dist/index.js",
     "release:publish": "node ./scripts/publish-release.mjs",
+    "release:publish:beta": "NPM_TAG=beta node ./scripts/publish-release.mjs",
     "sync:skills": "node ./scripts/sync-skills-repo.mjs",
     "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.
-