Spec: Harness Intelligence Product Monorepo Foundation

User Input

/goal Achieve the full M1 Monorepo Foundation Module milestone for the Devpunks Harness Intelligence project in /Users/stefan/Desktop/repos/wearedevpunks-cli.

Relevant IP-96 Linear scope:

• IP-96 establishes the Harness Intelligence product monorepo without changing current CLI behavior.
• IP-109 requires the operator to keep running existing punks/dp commands after the Turborepo shell is introduced.
• IP-110 requires the current CLI executable to live under apps/cli, not as a shared package.
• IP-111 requires build/typecheck/test validation through Turborepo against changed apps and packages.

Context

Harness Intelligence is no longer just the local punks CLI repository. It needs a product monorepo foundation that can hold the executable CLI, future backend/API control plane, private wiki, parked web surface, and shared packages without breaking current operator workflows. The affected roles are Devpunks operators using punks/dp, engineers adding app/package work, and future agents relying on scoped repo guidance.

Non-Goals

• Rewriting CLI internals beyond what is required for relocation.
• Implementing the final backend/API contract.
• Implementing public web product behavior.
• Designing full CI beyond the root validation model.
• Extracting shared contracts before another app consumes them.

Acceptance Criteria

• The repository is a Turborepo/workspace monorepo with root package workspaces for apps/* and packages/*.
• Root build, typecheck, test, dev, local CLI, release, baseline, skill sync, and database scripts delegate through turbo run package tasks.
• apps/cli owns the npm executable package and exposes the existing devpunks, dp, and punks bin entries.
• Existing CLI build, test, local, baseline, release, and skill-sync workflows are available from the CLI app package.
• Existing punks/dp scaffold and update behavior is preserved after relocation.
• Other apps and packages do not import from apps/cli internals.
• The monorepo includes app boundaries for apps/api, apps/wiki, and apps/web.
• The monorepo includes package boundaries needed by the foundation, including shared config/env/ui/db/contract packages.
• Relevant apps and packages expose their own build, check-types, test, dev, or domain scripts where applicable.
• Changed-package validation can be run with Turborepo filters or full root Turborepo tasks.
• Scoped AGENTS.md guidance and CLAUDE.md symlink mirrors exist for root, docs, apps, and packages that own independent work.
• Docs and runbooks explain the monorepo shape, CLI relocation, validation commands, and scaffold behavior changes.

Constraints

• CLI behavior preservation outranks structural neatness.
• Root scripts must not bypass Turborepo ownership for app/package tasks.
• Prompt/spec resolution logic stays in this repo and consumer-repo product logic must not leak into the CLI.
• The Hono backend scaffold is temporary; backend product work belongs to later Effect HTTP router/layer scope.
• apps/wiki owns durable wiki source content while docs/ owns operator runbooks and implementation references.

Technical Notes

• The foundation scaffold was created from Better-T-Stack, then reconciled into the repository root instead of leaving a nested @punks/cli project.
• dp scaffold setup --repo-shape monorepo --baseline bundled was run after patching repo detection to ignore generated caches, skill templates, and test fixtures.
• Validation evidence for the foundation commit: bun run check, bun run check-types, bun run test, and bun run build.

Decision Log