Plan: IP-96 Harness Intelligence Product Monorepo Foundation

Initial Situation

The repository was a CLI-owned package. M1 requires it to become the Harness Intelligence product monorepo while preserving existing punks/dp operator behavior. The foundation commit 3f7890c already introduced the Better-T-Stack/Turborepo scaffold, moved the CLI to apps/cli, added app/package boundaries, reconciled dp-cli scaffold output, and validated root tasks.

Issue

IP-96 and its child stories require the monorepo shell to be explicit, verifiable, documented, and safe for future IP-97/IP-98 work:

• IP-109: operators can still run the existing CLI after Turborepo is introduced.
• IP-110: the current executable CLI lives under apps/cli.
• IP-111: validation can run through Turborepo for changed apps/packages.

Solution Shape

Treat the foundation commit as the implementation baseline, then close IP-96 by proving it satisfies the spec. Any remaining work is limited to evidence, documentation, review findings, and Linear/spec closeout. Do not expand into IP-97 contract work or IP-98 scaffold-model extraction.

Inner Skill Phases

• $grill-me: no open decision was needed; parent/child Linear issues define the scope and non-goals.
• $parallel-research: used for readonly foundation discovery and MultiplAI benchmark comparison before implementation.
• $swarm-planner: task graph is dependency-ordered and single-agent executable because the foundation is already committed.
• $tdd: validation targets are public CLI/Turbo behavior, not private implementation details.

Decision Ledger

Codebase Findings

• Root package.json uses Bun workspaces and delegates build/typecheck/test/dev/local/release/baseline/db commands through Turborepo.
• apps/cli/package.json owns devpunks, dp, and punks executable bins plus CLI build/test/local scripts.
• apps/api, apps/wiki, apps/web, and packages/* exist as monorepo boundaries.
• apps/wiki/content/docs/cli/* renders the existing CLI wiki domain into Fumadocs routes.
• apps/cli/src/core/detect.ts ignores generated cache/template/test fixture directories so dp scaffold setup detects real workspaces.

External Research Used

• Linear IP-96, IP-109, IP-110, and IP-111 current issue descriptions and statuses.
• MultiplAI benchmark for .devpunks, scoped AGENTS.md, symlinks, hooks, wiki/spec structure, and repo ergonomics.
• opensrc path effect, opensrc path vercel/next.js, opensrc path drizzle-team/drizzle-orm, and opensrc path better-auth/better-auth were resolved for source-backed guidance where later implementation needs them.

Dependency Graph

T1 -> T2 -> T3 -> T4

Tasks

T1: Verify CLI relocation and operator commands

• depends_on: []
• location: apps/cli, package.json, turbo.json
• description: Confirm apps/cli owns executable entries and root commands delegate to app package tasks through Turborepo.
• validation: bun run test, bun run build, and direct inspection of apps/cli/package.json bin entries.
• status: Complete
• log: Root package.json delegates via Turborepo and apps/cli/package.json owns executable bins and CLI scripts.
• files edited/created: package.json, turbo.json, apps/cli/package.json, apps/cli/src/**
• backlog_item_id: IP-109, IP-110
• backlog_item_url: https://linear.app/devpunks/issue/IP-109/operator-can-run-the-existing-cli-after-the-turborepo-shell-is, https://linear.app/devpunks/issue/IP-110/current-cli-executable-lives-under-appscli
• relation_mode: native
• assigned_skills: effect-authoring, simplify, turborepo, quality-types, tdd
• tdd_target: Root and CLI package tasks execute the relocated CLI behavior without broken imports or missing fixtures.
• review_mode: cli

T2: Verify monorepo validation model

• depends_on: [T1]
• location: package.json, turbo.json, apps/*/package.json, packages/*/package.json
• description: Confirm relevant apps/packages expose package-local tasks and root validation runs through Turborepo.
• validation: bun run check, bun run check-types, bun run test, bun run build.
• status: Complete
• log: Root validation commands pass through Turborepo; package-local task scripts exist for changed app/package validation.
• files edited/created: package.json, turbo.json, apps/*/package.json, packages/*/package.json
• backlog_item_id: IP-111
• backlog_item_url: https://linear.app/devpunks/issue/IP-111/validation-can-run-against-changed-apps-and-packages
• relation_mode: native
• assigned_skills: turborepo, quality-types, tdd, simplify
• tdd_target: Public root validation commands prove the monorepo can validate changed app/package work.
• review_mode: cli

T3: Verify wiki/docs/scaffold reconciliation

• depends_on: [T2]
• location: apps/wiki, docs, .devpunks, .agents, .claude, .codex, .cursor, .opencode
• description: Confirm the dp-cli scaffold output was reconciled into real scoped prompts, symlinks, hooks, subagent manifest, and Fumadocs-backed wiki pages.
• validation: bun run build --filter=@punks/wiki, symlink inspection, .devpunks/scaffold-manifest.json manifest inspection.
• status: Complete
• log: dp scaffold setup output was reconciled into scoped prompts, symlink mirrors, harness agents, lint specs, and Fumadocs wiki pages.
• files edited/created: .devpunks/**, .agents/**, .claude/**, .codex/**, .cursor/**, .opencode/**, apps/wiki/**, docs/**
• backlog_item_id: IP-96
• backlog_item_url: https://linear.app/devpunks/issue/IP-96/establish-harness-intelligence-product-monorepo
• relation_mode: native
• assigned_skills: dp-cli, docs-ingest-phase, parallel-research, simplify, next-best-practices
• tdd_target: Wiki build exposes Harness/CLI domain pages instead of default Fumadocs sample content.
• review_mode: cli

T4: Review, docs-ingest-phase, and Linear closeout

• depends_on: [T3]
• location: apps/wiki/specs/cli/IP-96-monorepo-foundation, docs, Linear IP-96/IP-109/IP-110/IP-111
• description: Run findings-first review, resolve blocking findings, update implementation notes/docs-ingest-phase artifacts, commit, and close IP-96 plus child stories.
• validation: Review issue list is empty or explicitly deferred with rationale; final bun run check, bun run check-types, bun run test, bun run build; Linear statuses updated only after validation.
• status: Complete
• log: Review gate completed locally after two read-only review workers timed out; docs-ingest-phase ingested one flow and three concepts; final validation passed.
• files edited/created: apps/wiki/specs/cli/IP-96-monorepo-foundation/**, apps/wiki/content/docs/cli/**, apps/wiki/content/docs/cli/**
• backlog_item_id: IP-96
• backlog_item_url: https://linear.app/devpunks/issue/IP-96/establish-harness-intelligence-product-monorepo
• relation_mode: native
• assigned_skills: parallel-research, simplify, docs-ingest-phase, improve-codebase-architecture, tdd
• tdd_target: Closeout evidence links each IP-96 child acceptance signal to passing validation or concrete repository evidence.
• review_mode: cli

Testing Strategy

• Always run root bun run check, bun run check-types, bun run test, and bun run build.
• Use targeted bun run build --filter=@punks/wiki when wiki content changes.
• Treat nonfatal Next metadata warnings as residual unless they break build output or become part of the requested scope.

Risks and Mitigations

• Large move hides regressions: mitigate with CLI tests, root typecheck/build, and manifest/symlink inspection.
• Generic scaffold output drifts from Harness shape: mitigate by keeping scoped AGENTS.md, subagent manifest, and docs hand-reconciled after dp scaffold setup.
• IP-97/IP-98 scope leakage: mitigate by preserving temporary backend/contract notes without implementing final contract/scaffold shared model here.

Validation Gates

• Gate 1: CLI relocation evidence satisfies IP-109/IP-110.
• Gate 2: Turborepo validation evidence satisfies IP-111.
• Gate 3: Review finds no blocking unresolved issues.
• Gate 4: Linear status changes only after commit and validation.

Unresolved Questions

None for IP-96. Backend contract/API shape remains intentionally deferred to IP-97.