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.

Q1

Question: What is the canonical product boundary for "Harness Intelligence"?

Accepted answer:

• Harness Intelligence is the Devpunks AI engineering operating system: a documented methodology plus validated scaffold distribution system that turns repos into trustworthy AI-assisted workspaces.
• It is intentionally broader than the existing CLI, but still grounded in concrete delivery surfaces: scaffold data, CLI, backend, docs/wiki, validation, and public communication.
• The repo should be rethought around the Engineering OS boundary, not as a narrow distribution tool or a docs-only methodology site.

Branch B: Distribution Architecture

Purpose: define Turborepo shape, app/package boundaries, backend role, CLI role, baseline/data flow, and public surfaces.

Q2

Question: Should the Effect backend become the authoritative distribution/control plane, or should it only assist the CLI?

Accepted answer:

• The Effect backend should become the authoritative distribution/control plane.
• The CLI should be the local executor, cache, and client.
• Backend owns scaffold baseline registry, channels, versions, compatibility metadata, validation/provenance results, and public API surfaces consumed by docs and CLI.
• CLI owns local repo scanning, interactive setup, filesystem writes, offline bundled fallback, diff/update UX, and local operator ergonomics.
• Docs/wiki owns theory, criteria, trust model, implementation rules, and adoption guides.
• Landing owns public framing and proof narrative.

Q9

Question: Should the CLI call the backend live by default, or should release baselines remain the default distribution channel?

Accepted answer:

• Keep release baselines as the default distribution channel.
• The CLI should not require live backend calls to apply scaffold output inside local repositories.
• Baseline-first distribution remains important for deterministic setup, offline fallback, repeatability, and trust.
• The backend can still be authoritative for registry/control-plane responsibilities, but the CLI consumes versioned baseline artifacts as the practical distribution unit.

Q10

Question: How does the CLI distribute Harness Intelligence in practice?

Accepted answer:

• The CLI distributes the harness through dynamic usage by AI agents, not primarily through an MCP API.
• AI agents are expected to consume the CLI to retrieve and place:
  • skills
  • root prompts
  • .agents/ folders
  • symlinks and compatibility mirrors
  • scoped prompts for detected packages/apps or relevant repo scopes
  • hooks
  • subagent templates
  • scaffold metadata under .devpunks/
• The CLI should detect repository structure and place scoped prompts into the relevant apps/packages/scopes.
• The CLI is the local application/distribution mechanism for the harness, while the backend is the authority/control plane and baselines remain the artifact channel.
• The harness distribution includes external CLI/tool dependencies, not only markdown/context files.
• Required or optional toolchain expectations include:
  • skills, including installation/provisioning of the internal Devpunks dp-cli skill
  • opensrc for source inspection
  • agent-browser for browser/e2e validation
  • portless for parallel localhost subdomain allocation and avoiding worktree port collisions

Q3

Question: What Turborepo topology should this repo target?

Accepted answer:

• The repo should become a product monorepo with explicit application and package boundaries.
• Target topology:

apps/
  web/        public landing and product site
  wiki/       public Fumadocs docs/wiki app and canonical source content owner
  api/        Effect backend/control plane
  cli/        punks/dp CLI executable

packages/
  contract/    shared Effect HttpApi contract used by `apps/api` and `apps/cli`
  scaffold/   shared scaffold contract/model only if imported by apps such as `apps/cli` and `apps/api`
  config/     shared TypeScript/build/config support as needed
  ui/         only if landing/wiki share real UI primitives

• apps/wiki is the Fumadocs docs webapp and owns the source content.
• Do not introduce a separate content/harness layer now; that would be speculative until another runtime/app genuinely needs to consume the same source files.
• Existing root CLI code should eventually move under apps/cli because it is an executable app, not a shared library package.
• Internal packages must not import sibling apps.
• If shared API definitions are needed by both apps/cli and apps/api, extract those definitions into packages/contract.
• If shared scaffold code is needed by both apps/cli and apps/api, extract only that stable shared contract/model into packages/scaffold.

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.

Q4

Question: What should the wiki's theory/criteria model be organized around?

Accepted answer:

• Wiki content must follow the existing wiki structure and docs-ingest-phase contract: domain indexes, flows/, concepts/, source ingest metadata, wiki index, and wiki log.
• In the target monorepo, apps/wiki is both the Fumadocs app and the canonical source-content owner.
• Do not introduce an invented separate information architecture that bypasses the wiki/domain contract.
• Harness theory should be stored primarily as concepts and flows, not as loose narrative pages.
• Candidate concepts include:
  • Harness
  • context engineering
  • why prompt engineering is a dead/incomplete framing
  • progressive disclosure
  • skills as workflow wrappers
  • lazy skill loading
  • AGENTS.md as system-prompt/project-policy surface
  • prompt scopes: repo root prompt, .agents/ project prompt, ~/.agents global computer prompt
  • hooks
  • feedback loops
  • human-in-the-loop single-plan mode
  • subagent parallel mode
  • validation gates through the tdd skill
  • backlog to spec to plan workflow
  • default skill packs
• Candidate flows include:
  • adopting a repository into the harness
  • running requirements grilling before backlog creation
  • backlog to spec to plan to implementation
  • authoring/maintaining scoped prompts
  • lazy-loading skills during a task
  • running validation gates before closeout
  • operating in single-plan mode vs parallel subagent mode
• The wiki should capture the whole default skill-pack model, including planning, quality, research, requirements, docs, subagents, frontend/backend/effect surfaces, and validation behavior.
• The existing cli domain should continue to own CLI mechanics. Harness Intelligence likely needs its own domain instead of forcing all theory into cli.

Q5

Question: Should Harness Intelligence be a separate wiki domain from CLI?

Accepted answer:

• Yes. Create a separate harness wiki domain for methodology, theory, criteria, trust model, default skill packs, and adoption flows.
• Keep the existing cli domain for punks/dp mechanics: baseline channels, scaffold manifests, setup/update behavior, pack catalogs, and local operator flows.
• Add a future backend domain when the Effect control plane exists and owns enough durable concepts/flows.
• Do not create a sales/company-communication domain yet unless public landing/sales material grows durable domain concepts of its own.
• Boundary examples:
  • skills as workflow wrappers belongs to harness.
  • skill catalog in baseline data belongs to cli.
  • skill registry API belongs to a future backend domain.

Q18

Question: What is the first harness wiki domain inventory?

Accepted answer:

• Create a first private harness domain inventory shaped by the existing wiki/docs-ingest-phase contract.
• Keep durable pages as concepts and flows, but use Fumadocs navigation/subsections to make the tree readable instead of a flat page wall.
• First concept inventory:
  • Harness
  • Context Engineering
  • Prompt Engineering as Dead Framing
  • Progressive Disclosure
  • Skill as Workflow Wrapper
  • Lazy Skill Loading
  • Prompt Scope
  • AGENTS.md
  • Global Computer Prompt
  • Project Prompt
  • Scoped Package/App Prompt
  • Hook
  • Feedback Loop
  • Human-in-the-Loop Plan Mode
  • Parallel Subagent Mode
  • Validation Gate
  • TDD Acceptance Gate
  • External Tool Contract
  • Default Skill Pack
  • Planning Skill Pack
  • Requirements Skill Pack
  • Research Skill Pack
  • Quality Skill Pack
  • Docs Skill Pack
  • Debug Skill Pack
  • Frontend Skill Pack
  • Backend Skill Pack
  • Effect Skill Pack
  • Subagent Template
  • Agent Memory Notes
• First flow inventory:
  • Adopt Repository Into Harness
  • Run Requirements Grill
  • Convert Grill To Backlog
  • Convert Backlog Story To Spec
  • Create Execution Plan
  • Orchestrate Parallel Implementation
  • Execute Spec Sequentially
  • Execute Spec In Parallel Waves
  • Run Browser Validation
  • Run Code Review Phase
  • Run Debug Agent Phase
  • Report Harness Issue Through CLI
  • Maintain Wiki After Implementation
  • Publish Baseline Update
  • Update Existing Harnessed Repo
• Do not create a page for every individual skill in v1. Model skill packs first; split individual skills only when a skill has enough theory or workflow contract to justify its own page.
• Suggested Fumadocs subnavigation:
  • Foundations: Harness, Context Engineering, Progressive Disclosure, Feedback Loop
  • Prompt Surfaces: Prompt Scope, AGENTS.md, Global Computer Prompt, Project Prompt, Scoped Package/App Prompt
  • Skills and Packs: Skill as Workflow Wrapper, Lazy Skill Loading, Default/Planning/Requirements/Research/Quality/Docs/Debug/Frontend/Backend/Effect Skill Packs
  • Execution Modes: Human-in-the-Loop Plan Mode, Parallel Subagent Mode, Subagent Template, Agent Memory Notes
  • Validation and Tools: Validation Gate, TDD Acceptance Gate, External Tool Contract, Hook
  • Lifecycle Flows: grill/backlog/spec/plan/implementation/review/debug/docs-ingest-phase/update/reporting flows

Q19

Question: How should the first harness wiki content be sourced/ingested?

Accepted answer:

• Do not create a synthetic SPEC.md directly from this grill just to feed docs-ingest-phase.
• The current grill artifacts are requirements discovery inputs for the next backlog/planning phases, not a reviewed/implemented spec folder.
• Follow docs-ingest-phase exactly when wiki ingest happens:
  • primary ingest starts from a real resolved spec folder under <wiki-root>/specs/<domain>/<spec>/
  • read SPEC.md
  • optionally read IMPLEMENTATION-NOTES.md
  • write flow pages first
  • then write concept pages
  • update ingest metadata, wiki log, and wiki index
• The future implementation/planning steps should create the actual specs under apps/wiki/specs/<domain>/<spec>/.
• After those specs are reviewed or implemented, docs-ingest-phase can index domain source under apps/wiki/content/docs/project/domains/harness/ and keep routed articles under apps/wiki/content/docs/harness/.
• Until then, keep the grill artifacts in docs/ as requirements records and handoff inputs, not as direct wiki source pages.

Q6

Question: What belongs in the public wiki vs private/internal material?

Accepted answer:

• Supersedes the initially recommended public-by-default wiki split.
• The wiki is meant to be a private company-internal app.
• apps/wiki should optimize for internal trust, operational clarity, onboarding, and durable methodology capture for Devpunks colleagues.
• The wiki can include concrete company operating criteria, internal examples, real workflow decisions, and unsanitized theory-to-practice material as long as it remains internal.
• Public communication belongs to apps/web landing/product pages or other public docs surfaces, not the internal wiki.
• Public pages may summarize or derive from wiki concepts, but the internal wiki remains the richer source of truth.

Q7

Question: What should the public landing page expose if the real wiki is internal?

Accepted answer:

• The public landing page should expose the promise, evidence shape, and sanitized operating model.
• The private wiki remains the deep operating source of truth.
• Public landing scope:
  • what Harness Intelligence is in plain terms
  • why Devpunks engineers work faster and more safely with AI
  • operating principles such as context engineering, workflow-wrapped skills, validation gates, and human oversight
  • a sanitized lifecycle: discover -> plan -> implement -> validate -> document
  • trust/proof points: repeatable setup, repo-aware guidance, validation before closeout, documented decisions
  • CTA toward Devpunks services, not self-serve public docs
• Avoid public exposure of raw prompts/system policies, full internal wiki content, internal skill-pack implementation details, client/project-specific examples, or wording that makes the harness look like "just prompts".

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.

Q8

Question: What must exist before colleagues are expected to trust and use the harness?

Accepted answer:

• Adoption requires a trust gate bundle, not just docs or CLI installation.
• Minimum trust gate:
  • internal wiki onboarding path covering what the harness is, how to use it, and how not to misuse it
  • one golden repo adoption walkthrough showing before/after scaffold, generated files, expected agent behavior, and validation
  • harness criteria checklist covering repo readiness, prompt scopes, skill selection, hooks, subagents, validation gates, and docs/wiki hygiene
  • validation story distinguishing automatic verification, human verification, and remaining judgment
  • failure model covering stale prompts, over-broad subagents, missing validation, bad docs, and blind trust in AI output
  • operator runbooks for scaffold init, scaffold setup, update, baseline release/update, and skill pack maintenance
  • support/feedback loop for colleague friction and baseline improvements
• Trust should come from explicit boundaries, proof, and failure handling rather than claims that AI output is safe by default.

Q16

Question: How should harness adoption and rollout be measured?

Accepted answer:

• Supersedes the proposed repo-artifact-only metric model.
• Adoption should be measured primarily from actual CLI/runtime distribution telemetry:
  • CLI runs
  • baseline pulls
  • artifact reads/downloads
  • update checks
  • authenticated channel resolution
  • project identity inferred from the git remote repository name when available
• Vercel Blob/bucket reads can be useful input for baseline-pull tracking.
• Metrics must filter out:
  • internal testing reads
  • debug reads
  • localhost development
  • CI/publish validation noise when not representative of colleague usage
  • repeated cache misses/retries that inflate usage
• Supersedes the earlier cwd_leaf idea.
• Do not send pwd or full absolute local paths by default; they can leak usernames, client names, private folder structures, and machine details.
• Prefer a normalized project identifier payload such as:
  • git remote repository name when safe and available
  • scaffold manifest project id if/when introduced
  • baseline/channel/version
  • command name and outcome
• Repo artifact evidence such as .devpunks/scaffold-manifest.json, scoped prompts, and completed lifecycle artifacts remains useful qualitative proof, but should not be the primary adoption metric.
• If useful, add proper Effect-TS observability instrumentation in apps/api to track trusted events such as baseline resolution, artifact URL issue, CLI auth, and pull outcomes.
• Telemetry should support trust/adoption decisions without becoming invasive or noisy.

Q17

Question: Who owns rollout and support once colleagues start using the harness?

Accepted answer:

• Use central harness ownership plus project-local adoption ownership.
• Harness maintainers own:
  • baseline quality
  • default skill packs
  • required toolchain contract
  • CLI release/baseline release process
  • private wiki methodology
  • trust gate material
  • telemetry/observability interpretation
  • fixing systemic harness issues
• Project owners own:
  • deciding when their repo is ready to adopt
  • running scaffold setup/update
  • reviewing scoped prompt placement
  • keeping project-specific prompts/docs truthful
  • reporting friction back to harness maintainers
  • not treating the harness as a substitute for engineering judgment
• Reporting should be implemented into the CLI, not left only as a manual social process.
• Agents should be able to report encountered harness issues through the CLI when asked by the user.
• The internal dp-cli skill should explicitly guide agents to report relevant scaffold/tooling/skill/prompt issues back through the CLI.
• Feedback should be structured enough to become wiki/runbook updates, skill changes, hook changes, CLI fixes, or baseline releases.
• Systemic issues become central backlog items. Project-specific quirks stay local unless they generalize.

Q11

Question: What is the core Harness Intelligence workflow?

Accepted answer:

• Harness Intelligence is a lifecycle of skills, artifacts, prompts, validation gates, and feedback loops, not a single CLI command.
• Requirements phase:
  • requirements-grill uses grill-me plus branch, completion, log, and status management.
  • It produces durable grill artifacts formatted for the next step.
• Backlog phase:
  • write-backlog consumes requirements-grill logs/status.
  • It creates backlog/tasks in the chosen system such as Linear or GitHub.
  • It structures work as modules/milestones, epics, stories/subtasks, and native blocker/blocked-by relations.
• Planning phase:
  • parallel-research may be used for readonly context gathering.
  • create-spec turns stories into specs.
  • create-plan runs a smaller grilling pass to close open questions.
  • swarm-planner designs a task pipeline that supports parallel execution with explicit precedence and conflict avoidance.
  • Each task states the skills needed.
  • tdd is the crucial acceptance-criteria layer: red-to-green tests are given to each task where applicable.
  • opensrc is the first external CLI tool: agents use it to inspect upstream package/source behavior instead of guessing.
  • Scoped AGENTS.md prompts are explicitly discovered during planning.
• Coding phase:
  • implement-spec combines the spec and plan.
  • It resolves the target spec folder under apps/wiki/specs/<domain>/<spec>/.
  • It follows the shared execution lifecycle, notes, tech-debt, acceptance audit, and finalization contracts.
  • It chooses exactly one execution mode: sequential or parallel.
  • In Codex parallel mode, it applies the Codex-only worker reasoning policy before spawning workers.
  • It records the chosen mode under Execution mode in IMPLEMENTATION-NOTES.md before coding.
  • It updates PLAN.md, IMPLEMENTATION-NOTES.md, and spec-linked tech debt after each completed task or wave.
  • If backlog sync is in scope, epic/story bodies stay product-facing; native metadata or comments carry execution sync.
  • It finishes with shared acceptance audit and spec finalization.
• Browser/e2e validation:
  • agent-browser is the second external CLI tool.
  • It performs automated browser/frontend validation against the actual app when relevant.
• Localhost/worktree support:
  • portless may be used for parallel localhost subdomain allocation and to avoid port collisions across worktrees.
• Review phase:
  • /code-review uses simplify and improve-codebase-architecture.
  • It checks clarity, overcomplexity, architectural friction, and review-grade risks.
• Debug phase:
  • agent-debug uses scoped logs and endpoint listening for user-test log data.
  • It iterates automatically from user actions and fresh runtime evidence.
• Documentation/closeout:
  • docs-ingest-phase updates the private wiki/docs and backlog after implementation evidence exists.
• Cross-cutting harness properties:
  • skills wrap best practices by pack/language/framework
  • progressive disclosure governs context gathering
  • hooks provide automatic checks
  • scoped system prompts activate the right guidance per repo/app/package
  • subagent templates enable more specific spawns with clearer context
  • notes/diary/journal memory is autonomously checked and maintained by agents

Q30

Question: What is a Harness phase, and should coding, review, debugging, and docs ingest be separate goal calls or one delivery wrapper?

Accepted answer:

• A Phase is a goal-facing wrapper skill: a public orchestration entrypoint that owns one lifecycle slice, delegates to inner skills, defines entry and stop conditions, and maintains that slice's durable artifacts and validation gates.
• A phase is not just a loose process step. It is the unit a /goal can invoke and iterate.
• Keep the requirements phase HITL and brainstorming-heavy:
  • requirements-grill closes product/architecture branches, glossary, axioms, and parked scope.
  • write-backlog consumes grill artifacts after the requirements gate closes.
• The execution side should use a combined delivery wrapper instead of isolated goal calls:
  • coding through create-spec -> create-plan -> implement-spec
  • review after every coding run
  • optional debugging when validation or review exposes runtime failures
  • docs-ingest-phase after proven behavior changes
• Every coding run needs review, optional debugging, and docs-ingest-phase.
• Inner skills keep their ownership:
  • implement-spec still owns sequential/parallel implementation mode, TDD, browser validation when needed, simplify, notes, acceptance audit, manual checklist, and spec-linked tech debt capture.
  • review still uses readonly research and review lenses such as parallel-research, simplify, improve-codebase-architecture, and scoped directory skill guidance.
  • debugging still uses runtime evidence through debug-agent plus optional readonly parallel-research fan-out and bounded worker fixes.
  • docs-ingest-phase still owns source ingest and Fumadocs projection.
• Goal loop is the iterative goal-mode run that repeats one or more phases until the stated scope is complete or a concrete blocker is proven.

Q31

Question: Are phases themselves "goalized", or should goal prompt generation be a separate skill?

Accepted answer:

• Phases are not themselves goalized.
• A phase is a wrapper skill with its own contract, inner skills, artifacts, and gates.
• Goal-mode prompt generation is handled by a separate skill named goalify.
• goalify generates goal prompts from a requested scope, relevant skills/phases, handoffs, examples, and repository context.
• goalify is informed by the long-form goal prompt examples already used for:
  • the Fumadocs/wiki route restructuring goal
  • the .wav/LiveKit acceptance iteration goal
• requirements-phase stays human-centric and is normally not goalized.
• delivery-phase is goal-compatible and should preserve implement-spec's parallel parameter by passing the same parallel/sequential choice through.
• debugging-phase and resolve-debt can also be goal-compatible, but each becomes its own separate goal family because their entry artifacts differ:
  • runtime failure evidence for debugging
  • canonical debt file for debt resolution

Q32

Question: Should review be a public standalone phase skill, or only an internal phase inside delivery-phase?

Accepted answer:

• review-phase should be a public standalone skill.
• delivery-phase must also call review-phase automatically after every implementation run.
• Standalone review-phase is useful for manual review workflows, external edits, PRs, merged branches, suspicious code, or explicit review-only goals.
• review-phase is readonly by default and findings-first.
• Its review lenses include:
  • parallel-research for independent readonly checks
  • simplify for clarity, overcomplexity, and unnecessary abstraction
  • improve-codebase-architecture for architectural friction and module-depth opportunities
  • scoped skill guidance found in checked directories such as apps, packages, and docs
• Standalone review-phase does not edit code unless explicitly requested.
• When invoked inside delivery-phase, review findings can trigger fixes, debugging loops, or docs updates because delivery-phase owns completion.

Q33

Question: How should debugging-phase behave relative to delivery-phase?

Accepted answer:

• debugging-phase should be a public standalone skill.
• delivery-phase should invoke the same debugging loop only when delivery validation or review produces runtime evidence of a bug.
• Standalone debugging-phase entry artifacts include:
  • user-reported broken behavior
  • failing smoke checks
  • logs
  • recordings
  • runtime symptoms
• Standalone debugging-phase wraps:
  • debug-agent
  • optional readonly parallel-research
  • bounded fixes
  • focused tests or scenario reruns
  • review
• debugging-phase may run with parallel: true | false.
• debugging-phase owns evidence matrices and log references.
• Standalone debugging-phase exits when:
  • the bug is fixed
  • a concrete blocker is proven
  • the scope actually needs a spec/delivery goal
• Delivery-internal debugging starts only when implement-spec validation or review-phase finds a runtime failure.
• Delivery-internal debugging patches only inside the delivery scope.
• If a bug is broader than the current spec, delivery-phase must record tech debt or propose a separate debugging/debt goal instead of widening silently.

Q34

Question: Should docs ingest be a standalone phase, delivery-internal, or both?

Accepted answer:

• Docs ingest is both:
  • a delivery-internal phase after review/debug
  • an independently callable maintenance operation
• However, docs ingest currently wraps only docs-ingest-phase.
• Avoid creating a thin wrapper skill if it only delegates to one existing skill with no new orchestration.
• Prefer renaming or evolving docs-ingest-phase into the docs-ingest phase entrypoint if that yields clearer phase language.
• Delivery must run docs-ingest-phase after review/debug when docs work is needed.
• If implementation changed product behavior, architecture, setup, operator workflow, docs contracts, or spec domain knowledge, delivery must invoke the docs-ingest/docs-ingest-phase entrypoint.
• If no docs ingest is needed, delivery must record an explicit no-op reason in the final report or implementation notes.

Q35

Question: Should the tech debt public skill be tech-debt-phase, resolve-debt, or resolve-debt-phase?

Accepted answer:

• Use resolve-debt-phase as the public standalone skill name.
• "Tech debt phase" remains the lifecycle concept.
• resolve-debt-phase is clearer than tech-debt-phase because the operation is not generic debt management; it resolves one candidate or accepted debt item.
• resolve-debt-phase is clearer than resolve-debt because it is a standalone phase wrapper.
• Canonical entry artifact:
  • docs/reference/tech-debt/<domain>/<spec>/<debt-slug>.md
• If debt status is draft, run readonly validation first, then ask the user whether to accept, delete, or research more.
• If debt status is accepted, create or update a debt-resolution spec, then run delivery.
• If debt status is resolved, report no-op unless the user explicitly asks to inspect history.
• After delivery, mark the debt resolved, link the resolution spec and implementation notes, and sync the backlog mirror when available.

Q36

Question: Should docs ingest be the docs-ingest-phase public skill?

Accepted answer:

• Finalize docs-ingest-phase as the public docs ingest phase entrypoint.
• docs-ingest-phase is a real public phase entrypoint.
• It is not a new thin wrapper around another docs skill; it owns the existing docs ingest contract and references.
• delivery-phase calls docs-ingest-phase directly after review/debug.
• docs-ingest-phase runs after review/debug when required:
  • run docs-ingest-phase when implementation changed product behavior, architecture, setup, operator workflow, docs contracts, or spec domain knowledge
  • otherwise record an explicit no-op reason
• Existing docs-ingest-phase responsibilities remain owned by the renamed phase:
  • canonical domain source indexes under apps/wiki/content/docs/project/domains, apps/wiki/specs, and related source files
  • Fumadocs routed articles under apps/wiki/content/docs/harness, apps/wiki/content/docs/cli, or apps/wiki/content/docs/project
  • repo docs/ updates for architecture, setup, contracts, runbooks, and operator workflow
  • meta.json and access-control frontmatter preservation

Q37

Question: What implementation order should be used for the phase-wrapper skills?

Accepted answer:

• Implement leaves before composites, then prompt generation last.
• Order:
  1. Finalize docs-ingest-phase as the docs ingest phase entrypoint.
  2. Create review-phase.
  3. Create debugging-phase.
  4. Create delivery-phase.
  5. Create requirements-phase.
  6. Create resolve-debt-phase.
  7. Create goalify.
• docs-ingest-phase comes first because delivery-phase depends on the final docs phase name.
• review-phase comes before delivery-phase because delivery must call it after every implementation run.
• debugging-phase comes before delivery-phase because delivery can invoke debugging for scoped runtime failures found by validation or review.
• delivery-phase comes after its inner execution/review/debug/docs phase entrypoints are stable.
• requirements-phase can follow because it is human-centric and does not block delivery composition.
• resolve-debt-phase follows delivery because accepted debt resolution uses delivery after debt preflight.
• goalify comes last because it should generate prompts from the final phase contracts rather than from speculative names.

Q38

Question: Should docs-ingest-phase keep a backward-compatibility alias?

Accepted answer:

• No backward-compatibility alias.
• Use docs-ingest-phase directly as the public phase name.
• Update references accordingly wherever current operating guidance mentions the prior docs skill name.
• New phase skills and existing skill references should call docs-ingest-phase.
• Historical references only remain if they are intentionally archival; ordinary current docs/skills should be find-and-replace updated.

Q12

Question: What is the minimum useful backend/control-plane scope for v1 if release baselines stay default?

Accepted answer:

• Superseded in part by Q15.
• Backend v1 should be registry, provenance, authenticated baseline distribution, and adoption visibility, not live scaffold execution.
• The backend tells the truth; the CLI does the local work.
• Backend v1 owns:
  • baseline registry: channels, versions, bundles, changelogs, compatibility metadata
  • baseline contents: skill packs, hooks, tool requirements, prompts, subagent templates, scaffold metadata
  • provenance: source commit, production timestamp, validation status, known issues
  • adoption visibility: which internal repos/teams are on which baseline, through opt-in/manual/CLI-reported records as appropriate
  • trust dashboard: current recommended baseline, rollout notes, validation state, upgrade guidance
  • read API for CLI/docs/web metadata
  • internal auth if dashboard/backend surfaces are private
• Backend v1 does not own:
  • remote filesystem scaffold application
  • replacing the CLI with MCP
  • live scaffold execution inside repo setup
  • complex telemetry
  • full skill marketplace
• The local CLI remains responsible for applying scaffold output, checking/provisioning tool dependencies, placing prompts/hooks/skills/symlinks/manifests, and operating against detected repo scopes.

Q15

Question: How should CLI/auth/baseline distribution work if baseline data is private?

Accepted answer:

• The CLI can be distributed as an npm package, but internal runtime baseline access should be authenticated.
• Use Better Auth for CLI login, likely through device authorization flow:
  • dp auth login
  • browser approval against Devpunks auth
  • CLI stores a local token
  • CLI sends Authorization: Bearer <token> to apps/api
• Because baseline data currently lives in a private repo/release flow, unauthenticated remote baseline access is not a real product contract.
• Runtime target model:
  • CLI asks apps/api for the recommended baseline/channel.
  • apps/api verifies access.
  • apps/api returns baseline metadata and a signed/proxied artifact URL.
  • CLI downloads/caches the baseline and applies it locally.
• Vercel Blob is the likely artifact storage target for baseline artifacts.
• GitHub Releases are not the long-term runtime distribution contract. They can remain as a migration/CI/provenance detail if useful.
• During migration, do not make releases protected yet; keep the existing release flow simple while the backend/blob path is designed.
• Required harness tools include skills, opensrc, agent-browser, and portless; portless is not optional.

Q13

Question: What migration order should we plan for the repo rewrite?

Accepted answer:

• Migrate in behavior-preserving phases instead of starting with a CLI rewrite.
• Order:
  1. Add Turborepo/workspaces and move the current CLI into apps/cli without changing behavior.
  2. Extract scaffold core into packages/scaffold: baseline/catalog/manifest/rendering primitives.
  3. Create apps/wiki as the private Fumadocs app, move/convert current wiki content, add harness domain, preserve cli domain.
  4. Create apps/web public landing derived from private wiki concepts without exposing internals.
  5. Create apps/api Effect backend v1 for registry/provenance/adoption metadata around release baselines.
  6. Wire CLI to backend metadata while preserving baseline-first distribution.
  7. Build trust gate material: golden repo walkthrough, criteria checklist, onboarding, validation story, failure model.
  8. Consider CLI cleanup/rewrite only after extraction shows which internals are truly costly.
• The current CLI provides value and must not be discarded before its behavior is captured and protected.
• packages/scaffold should exist only as a shared internal package imported by apps/cli and apps/api; if no sibling app imports that contract yet, defer extraction.

Q21

Question: Should the CLI consume the API through Effect RPC or Effect HttpApi/HTTP client, and what shared package owns the contract?

Accepted answer:

• Prefer Effect v4 HttpApi/typed HTTP client for the CLI-to-backend v1 contract.
• Do not use raw untyped HttpClient for the core control-plane API unless a specific endpoint is intentionally outside the typed contract.
• Use Effect RPC only if/when the product needs RPC-specific behavior such as long-lived bidirectional/streaming workflows, richer request/response protocol semantics, or non-REST procedure semantics that justify the extra protocol layer.
• For v1, the backend operations are HTTP-shaped: auth-mediated baseline resolution, artifact URL issue, telemetry/report submission, adoption metadata, and trust dashboard data.
• HttpApi is a better default because it is schema-first, type-safe, produces typed clients, supports middleware/auth, and can generate OpenAPI/docs.
• The shared Turborepo package should be packages/contract, not packages/scaffold by default.
• Proposed package:

packages/contract/
  src/api.ts        Effect HttpApi definition
  src/schemas.ts    shared Schema models for requests/responses
  src/errors.ts     shared typed API errors
  src/security.ts   auth middleware/security declarations if shared

• apps/api imports packages/contract to implement handlers.
• apps/cli imports packages/contract to construct the typed client.
• packages/contract must not import either app.
• packages/scaffold remains valid only for shared baseline/scaffold schemas, catalog types, compatibility metadata, provenance shapes, and required-tool contracts that are imported by both apps/api and apps/cli.

Branch F: Backoffice and Project Mapping

Purpose: define the internal product surface for usage statistics, project/repository mapping, adoption visibility, and the boundary between product telemetry and system observability.

Q20

Question: Should Harness Intelligence build its own product backoffice for usage/project/repo stats, or reuse an observability frontend?

Accepted answer:

• Build a small first-party backoffice as a real Harness Intelligence product surface.
• Store product/adoption events durably in Postgres through apps/api.
• Use Effect/OpenTelemetry for system observability, traces, debugging, backend health, and instrumentation plumbing.
• Do not use an OpenTelemetry frontend as the main product backoffice.
• The backoffice should expose product-level entities and adoption views, not only low-level spans/logs/metrics.
• Product-level entities should include:
  • Project
  • Repository
  • Baseline / Channel
  • CLI Run
  • Artifact Pull
  • Harness Report
  • later, possibly Spec
• A Project can group one or more repositories.
• A Repository is identified initially by git remote repository name/slug, then enriched or linked centrally.
• Metrics should be grouped by project, repository, baseline/channel, CLI version, event type, time window, and environment filtering.
• The OTel layer remains useful for "what happened inside the system?"
• The first-party backoffice answers "which Devpunks projects adopted the harness, how often, where is friction, which baseline is trusted, and which repos are stale?"

Q22

Question: Where should the backoffice live?

Accepted answer:

• Create a separate apps/backoffice application.
• Do not hide the backoffice inside apps/web.
• apps/backoffice owns authenticated internal operational/product views for Harness Intelligence adoption, project/repo mapping, usage statistics, reports, baseline health, and administrative review workflows.
• apps/web remains the public/sanitized landing and company communication surface if/when that scope is implemented.
• apps/wiki remains the private Fumadocs knowledge/docs app and source-content owner.
• apps/api owns the backend/control plane, Postgres writes/reads, and typed API surfaces consumed by both apps/cli and apps/backoffice.
• packages/contract should include the shared typed API contract needed by apps/api, apps/cli, and apps/backoffice when applicable.
• The app split is justified because the backoffice has different audience, auth posture, product concerns, navigation, and operational workflows from the landing page.

Q23

Question: What is the minimum Postgres product schema for backoffice v1 if telemetry is collected only from CLI usage?

Accepted answer:

• Do not model Project and Repository as separate v1 concepts.
• For Harness Intelligence v1, the observable adoption unit is the repository/workspace seen by the CLI.
• Any higher-level project grouping can be derived later or added manually once real usage patterns justify it.
• The CLI can only reliably report facts it can observe locally from git, shell, environment, and its own runtime.
• The v1 persisted model should be remapped around available CLI-observed fields:
  • git remote repository slug/name
  • git remote URL/provider when safely available
  • current branch
  • default/upstream branch if safely available
  • current commit SHA
  • dirty/clean worktree state
  • git user name and email from local git config, subject to privacy/safety filtering
  • authenticated Devpunks user identity from CLI auth when available
  • hostname or machine identifier only if explicitly accepted later; do not assume it now
  • cwd leaf directory is not needed if git remote repository identity is available
  • CLI version
  • baseline/channel/version
  • required tool check results
  • event type and timestamp
  • environment/source flags for local/dev/debug/test/CI filtering
• The backoffice can still show "project-like" groupings, but v1 should treat those as labels/views over observed repositories, not a foundational separate domain model.
• This supersedes the earlier v1 schema idea where Project grouped one or more Repository records.
• Specs remain a future entity and should not be included in the v1 backoffice schema.

Q24

Question: Should Harness Intelligence v1 remove the Project concept if telemetry only observes repositories?

Accepted answer:

• No. Keep Project as a first-class product/backoffice concept in v1.
• In v1, Project means the repository observed from CLI usage.
• This matches the CTO/product language: track which projects/developers use the CLI, where "project" maps to a repository.
• Do not model a separate higher-level multi-repository project aggregate yet.
• The durable v1 entity can be named projects, with repository identity fields on it.
• Candidate project/repository identity fields:
  • id
  • remote_slug
  • remote_name
  • remote_url_hash or normalized safe remote URL
  • provider
  • default_branch or detected upstream branch when safely available
  • first_seen_at
  • last_seen_at
  • last_commit_sha
  • last_branch
  • last_dirty_state
  • archived_at
• CLI events should reference project_id.
• Developer/actor usage should be tracked separately from project identity.
• This supersedes Q23 only where Q23 says there is "no separate Project + Repository model"; the corrected rule is: keep Project, define it as repository for v1, and defer higher-level project grouping.

Q25

Question: Can Harness Intelligence v1 model a higher-level project aggregate above repositories?

Accepted answer:

• Yes, v1 can model a higher-level Project aggregate if there is a reliable source of truth or safe mapping path.
• Automatic usage tracking can only depend on data available to the CLI on the machine where it runs.
• The CLI should not assume access to Linear, GitHub org metadata, private company systems, or manual project catalogs unless the user/auth/backend explicitly provides those later.
• Automatic sources available from the running machine may include:
  • git remote -v
  • git config user.name
  • git config user.email
  • current branch, upstream branch, default branch hints, and commit SHA
  • working tree status
  • package/workspace metadata visible from files in the repo
  • repository root and repo leaf name if needed, but avoid sending cwd paths
  • authenticated CLI user/session
  • CLI flags/env that mark debug/test/local/CI contexts
• The backend/backoffice can maintain an explicit mapping layer:
  • observed repository identity -> project aggregate
  • project aggregate -> one or more observed repositories
  • project aggregate -> owner/team/status metadata
• If no external/manual mapping exists, the first ingestion path should create or update a repository-observed project candidate from git remote identity.
• This preserves Simone's model that stats can be grouped by repo/project while keeping automatic telemetry honest about its sources.
• Project = repository is an acceptable fallback, not a hard limitation.

Q26

Question: Should Harness Intelligence use Microsoft workspace login as the canonical developer identity?

Accepted answer:

• Yes.
• Use Better Auth as the application auth/session framework.
• Use Microsoft/Entra ID workspace login as the primary identity provider.
• Canonical developer identity should come from Microsoft workspace login.
• CLI login should route through the same Better Auth/Microsoft identity system used by API and backoffice.
• Backoffice auth should use Microsoft login.
• Git user.name and user.email remain observed telemetry metadata and fallback context, not canonical developer identity.
• Reuse/adapt the working dp-ai pattern where possible:
  • Better Auth Microsoft social provider
  • Microsoft tenant configuration
  • trusted provider account linking
  • admin/allowlist validation for OAuth users
  • backoffice login button using Microsoft social sign-in
• This keeps workplace identity aligned with the company Microsoft workspace while preserving git data as repo-environment evidence.

Q27

Question: What event taxonomy should v1 track for backoffice usage statistics?

Accepted answer:

• Track only happy-path, value-signaling product events in v1.
• Do not track noisy internal lifecycle steps as product statistics.
• Do not track:
  • setup.started
  • baseline.resolve.completed
  • update.checked
  • automatic background toolcheck.completed
• baseline.resolve is assumed to be an internal step before artifact pull and does not need its own statistics event.
• Tool checks may run automatically/background and would spam adoption dashboards if tracked as first-class stats.
• V1 product/adoption event taxonomy:
  • cli.auth.login.completed
  • cli.artifact.pull.completed
  • cli.scaffold.setup.completed
  • cli.scaffold.update.applied
  • cli.harness.report.submitted
• Detailed failures, noisy lifecycle traces, background checks, and debug timing belong to logs/OTel/debug surfaces, not the product adoption event stream.
• Each product event should carry the shared envelope:
  • project/repository identity
  • Microsoft actor identity when authenticated
  • git identity metadata as fallback/context
  • CLI version
  • baseline/channel/version when relevant
  • event timestamp
  • environment/source flags for filtering local/test/debug/CI noise
• Dashboards should count meaningful successful usage: authenticated users, pulled artifacts, completed setup, applied updates, and submitted reports.

Q28

Question: What should "developer usage" mean in the backoffice?

Accepted answer:

• Treat developer usage as operator/audit/contact context, not as a primary adoption KPI.
• The primary adoption unit is the project/repository.
• The CLI is a project-level tool. It is used heavily during scaffold setup/update, often by one operator, but the effect is repo-wide.
• A developer is the authenticated Microsoft user who performed a CLI action or submitted a report.
• Backoffice may show:
  • who initialized or updated a harnessed repo
  • who last pulled/applied a baseline
  • who submitted a report
  • who can be contacted for context
• Backoffice must not rank developers, score developers, compare developers, or present "AI usage by developer" as a core metric.
• Project dashboards should lead with repo/project state:
  • harnessed or not
  • baseline/channel/version
  • last setup/update
  • latest CLI version seen
  • submitted reports
  • stale baseline status
• Reports link to GitHub for v1, not Linear.
• GitHub is the v1 system of record for report follow-up because reports are closer to implementation/tooling issues than product-planning backlog items.

Q29

Question: What is the final v1 relationship between project usage and repositories?

Accepted answer:

• Introduce a ProjectUsage entity or equivalent project-usage aggregate in v1.
• ProjectUsage maps 1:n to observed repositories.
• Observed repositories remain the facts collected automatically from CLI execution on a developer machine.
• Project usage is the backoffice/adoption grouping used for statistics and operational review.
• The backend/backoffice can create a project-usage aggregate from the first observed repository and later map additional repositories into it.
• If no higher-level mapping is configured, a project-usage aggregate may contain exactly one observed repository.
• This replaces the earlier "Project = repository" fallback as the core model: repository is the observed source, project usage is the reporting aggregate.
• Suggested relationship:

project_usage
  1 -> n observed_repositories
  1 -> n cli_usage_events
  1 -> n harness_reports

observed_repository
  n -> 1 project_usage
  1 -> n cli_usage_events
  1 -> n harness_reports

• Automatic mapping inputs still stay limited to what the CLI can observe: git remote, repo metadata, authenticated Microsoft user, CLI runtime metadata, and safe environment flags.
• Manual/admin mapping in apps/backoffice is allowed and expected for grouping multiple repositories into one project usage aggregate.

Branch E: Company Communication

Purpose: define landing-page and sales narrative for how Devpunks engineers are AI-superpowered without becoming vague marketing copy.

Q14

Question: What should the public landing page's message hierarchy be?

Accepted answer:

• Park exact landing message hierarchy for later planning.
• Directionally, the landing page should communicate that Devpunks engineers use a structured AI harness rather than "just using AI".
• The tone should be semi-technical, concrete, and not marketing fluff.
• The landing page should derive sanitized proof/narrative from the private wiki, but detailed content/copy is not defined in this grill.