Plan: IP-100 Harness Methodology Domain

Initial Situation

The wiki already has a harness source domain and one routed page, but it does not yet represent the M2 methodology domain. Navigation is flat, concept coverage is partial, and lifecycle flows are not represented.

Issue

IP-100 must absorb IP-119, IP-120, and IP-121. The domain must organize methodology into readable sections, cover the initial concept inventory, and explain the main lifecycle flows from repository adoption through delivery closeout and baseline update.

Solution Shape

Lock navigation first, then index domain source under apps/wiki/content/docs/project/domains/harness, then write concise routed MDX pages under apps/wiki/content/docs/harness. Keep CLI mechanics linked but separate. Update indexes, meta files, and docs-ingest bookkeeping in the same pass.

Inner Skill Phases

• $grill-me: no live grill needed; grill artifacts and Linear child criteria define scope.
• $parallel-research: used to synthesize source requirements and route conventions in parallel.
• $swarm-planner: tasks split by IA, concepts, flows, projection, and validation.
• $tdd: route/build/browser checks are the acceptance tests.

Decision Ledger

Codebase Findings

• Harness source index exists at apps/wiki/content/docs/project/domains/harness.mdx.
• Routed harness index exists at apps/wiki/content/docs/harness/index.mdx.
• meta.json for harness currently has only index and phase-goal-workflow.
• Existing source/routed page style is concise, frontmatter-driven, and link-oriented.

External Research Used

• Linear fetch confirmed IP-100, IP-119, IP-120, and IP-121 descriptions, parent links, statuses, and M2 milestone.
• Product source synthesis used docs/reference/harness-intelligence.md, docs/harness-intelligence-grill-log.md, and docs/harness-intelligence-grill-status.md.

Dependency Graph

T1 -> T2 -> T4 -> T5

T1 -> T3 -> T4 -> T5

Parallel Execution Waves

• Wave 1: T1 navigation lock.
• Wave 2: T2 concept source pages and T3 flow source pages can run in parallel because they own disjoint source files.
• Wave 3: T4 routed projection/meta/index/log integration.
• Wave 4: T5 validation, review, and closeout.

Tasks

T1: Lock harness navigation and source IA

• depends_on: []
• location: apps/wiki/content/docs/project/domains/harness.mdx, apps/wiki/content/docs/harness/meta.json, section index pages
• description: Establish Foundations, Prompt Surfaces, Skills and Packs, Execution Modes, Validation and Tools, and Lifecycle Flows as the durable navigation model.
• validation: Harness meta includes section folders; routed index shows readable grouped cards.
• status: Complete
• log: Harness navigation grouped into six sections with source index links.
• files edited/created: apps/wiki/content/docs/project/domains/harness.mdx, apps/wiki/content/docs/harness/**/index.mdx, apps/wiki/content/docs/harness/meta.json
• backlog_item_id: IP-119
• backlog_item_url: https://linear.app/devpunks/issue/IP-119/harness-domain-navigation-is-organized-into-readable-subsections
• relation_mode: native
• assigned_skills: docs-ingest-phase, next-best-practices, simplify
• tdd_target: Harness navigation is grouped and not a flat wall.
• review_mode: browser

T2: Write compact harness concept inventory

• depends_on: [T1]
• location: apps/wiki/content/docs/project/domains/harness, apps/wiki/content/docs/harness
• description: Add/update source concept pages covering harness, context engineering, progressive disclosure, prompt scopes, skills, hooks, validation gates, external tools, subagents, memory notes, and skill packs.
• validation: Concept inventory in source index maps every IP-120 required concept to at least one source/routed page.
• status: Complete
• log: Added compact concept pages organized around domain concepts, prompt surfaces, skill packs, execution modes, and validation/tools.
• files edited/created: apps/wiki/content/docs/project/domains/harness.mdx, apps/wiki/content/docs/harness/**/*.mdx
• backlog_item_id: IP-120
• backlog_item_url: https://linear.app/devpunks/issue/IP-120/harness-methodology-concept-inventory-is-represented-in-the-wiki
• relation_mode: native
• assigned_skills: docs-ingest-phase, simplify, quality-types
• tdd_target: IP-120 concept checklist is represented without one page per individual skill.
• review_mode: cli

T3: Write harness lifecycle flow inventory

• depends_on: [T1]
• location: apps/wiki/content/docs/project/domains/harness, apps/wiki/content/docs/harness/lifecycle-flows
• description: Add flow pages for adoption/requirements/planning/delivery/validation/review/debug/docs/report/baseline/update lifecycle coverage.
• validation: Flow inventory maps every IP-121 required flow to source and routed pages.
• status: Complete
• log: Added three lifecycle flow source pages covering adoption to closeout, delivery validation, and baseline/update feedback.
• files edited/created: apps/wiki/content/docs/project/domains/harness.mdx, apps/wiki/content/docs/harness/lifecycle-flows/*.mdx
• backlog_item_id: IP-121
• backlog_item_url: https://linear.app/devpunks/issue/IP-121/harness-lifecycle-flows-are-represented-in-the-wiki
• relation_mode: native
• assigned_skills: docs-ingest-phase, simplify
• tdd_target: Flow checklist is covered without plan-level implementation instructions.
• review_mode: cli

T4: Project harness domain into Fumadocs

• depends_on: [T2, T3]
• location: apps/wiki/content/docs/harness, apps/wiki/index.md, apps/wiki/log.md, docs/README.md
• description: Create routed MDX projection pages, update meta files, source index counts, wiki log, and root docs references.
• validation: jq empty for all touched meta files; browser routes render for all sections.
• status: Complete
• log: Routed projection created with six navigation sections, concept pages, flow pages, and updated wiki bookkeeping.
• files edited/created: apps/wiki/content/docs/harness/**, apps/wiki/index.md, apps/wiki/log.md, docs/README.md
• backlog_item_id: IP-119, IP-120, IP-121
• backlog_item_url: https://linear.app/devpunks/issue/IP-119/harness-domain-navigation-is-organized-into-readable-subsections
• relation_mode: native
• assigned_skills: docs-ingest-phase, next-best-practices, turborepo
• tdd_target: Source and routed navigation are synchronized and renderable.
• review_mode: mixed

T5: Review, validate, and close out

• depends_on: [T4]
• location: apps/wiki/specs/cli/IP-100-harness-methodology-domain, validation commands, browser smoke
• description: Run review, fix blocking findings, update implementation notes, and record validation/deployment/Linear evidence.
• validation: bun run check, bun run check-types, bun run build --filter=@punks/wiki, browser smoke, review report with no blocking findings.
• status: Complete
• log: Review and validation completed; Vercel remained blocked by missing project linkage/access.
• files edited/created: apps/wiki/specs/cli/IP-100-harness-methodology-domain/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-100
• backlog_item_url: https://linear.app/devpunks/issue/IP-100/create-the-harness-methodology-domain
• relation_mode: native
• assigned_skills: review-phase, debugging-phase, tdd, simplify
• tdd_target: Whole harness domain acceptance checklist maps to passing route/build/browser evidence.
• review_mode: mixed

Testing Strategy

• Validate all changed meta.json files with jq empty.
• Run bun run check.
• Run bun run check-types.
• Run bun run build --filter=@punks/wiki.
• Run local wiki server and smoke /docs/harness plus one route per section.

Risks and Mitigations

• Content sprawl: use compact pages and section indexes instead of individual pages for every skill.
• Methodology/CLI blur: each relevant page links CLI mechanics out to /docs/cli instead of duplicating them.
• Routed/source drift: update source index, routed meta, wiki index, and wiki log in one pass.

Validation Gates

• Gate 1: IA locked and meta valid.
• Gate 2: Concept checklist covered.
• Gate 3: Flow checklist covered.
• Gate 4: Browser/build/typecheck prove routes render.

Unresolved Questions

None blocking M2. Future docs-ingest output may split compact pages when real implemented specs add deeper domain knowledge.