ai-harness-bootstrap

name	ai-harness-bootstrap
description	Use when creating, scaffolding, or updating the repository AI harness in VS Code. Trigger on requests to bootstrap or refresh instructions, prompts, agents, hooks, skills, or memory layers while preserving useful existing structure and avoiding monolithic always-on context.
argument-hint	[goal or scope] [constraints]
user-invocable	true
disable-model-invocation	true

AI Harness Bootstrap

Bootstrap or refresh the full repository AI harness. Do not limit work to this skill folder.

Use the official VS Code customization model correctly:

• .github/copilot-instructions.md for thin always-on repo rules
• AGENTS.md for routing, instruction priority, and progressive disclosure
• .github/instructions/*.instructions.md for scoped rules
• .github/prompts/*.prompt.md for lightweight repeatable workflows
• .github/agents/*.agent.md for role-specialized behavior
• .github/skills/* for richer reusable capabilities
• .github/hooks/*.json for deterministic lifecycle automation
• .github/harness/*.yaml for explicit governance and runtime-role configuration
• memory/* for persisted volatile task context in Markdown, YAML, and JSON

Use helper resources only where they materially improve governance or maintainability:

• .github/harness/governance-profile.yaml for explicit governance mode and verifier strategy
• memory/audit-log.jsonl for machine-readable provenance alongside the human-facing memory/log.md

In this repository, .sea/skills is canonical and .github/skills is the VS Code discovery mirror.

If you encounter an external agent/plugin pack such as .claude/plugins/@sea/cdaa-coherence, absorb its reusable architectural primitives into the harness instead of mirroring the plugin tree verbatim.

Primary Goal

Create or update a maintainable harness that acts as an operating scaffold, semantic router, and lightweight memory system for GitHub Copilot and IDE agents with full repo access.

The scaffold must be able to build and maintain all major harness surfaces already discussed in this repository:

• architecture synthesis
• ADR, PRD, and SDS thought-partner flows
• conversation-to-spec with guarded confirmation semantics
• domain-expert communication overlays for non-technical requirement work
• case orchestration and PM-style staged routing
• cognitive artifact generation as a support workflow
• deployment and release routing with explicit safety and verification boundaries
• coherence measurement and slow-layer reflection
• harness bootstrap and harness audit
• runtime harness configuration for multi-runtime governance and handoff boundaries

Required Operating Model

Ensure the harness explicitly teaches:

• a three-layer context split:
  • stable operating contract
  • project overlay
  • volatile working memory
• inspect-before-ask behavior for IDE agents with full repo access
• progressive disclosure instead of a monolithic root instruction file
• disk-backed working memory that stays distilled
• a concrete work loop: inspect, route, decide mode, implement or propose, validate, update memory if useful, leave the next move clear

ACE Application

Apply ACE (Agentic Context Engineering) to the harness itself:

• treat the harness as an evolving playbook, not a static prompt bundle
• use structured incremental updates to avoid brevity bias and context collapse
• keep durable harness strategy in memory/playbook.md
• keep raw or newly distilled execution feedback in memory/reflections.md
• use natural execution feedback from lint, validation, bootstrap runs, audits, and real usage to improve the harness over time
• separate offline contexts from online contexts:
  • offline: .github/copilot-instructions.md, AGENTS.md, scoped instructions, prompts, agents, skills
  • online: memory/current-task.md, memory/active-context.yaml, memory/reflections.md, memory/log.md

AutoHarness Application

Apply the useful parts of AutoHarness to the repo-native harness without turning the repository into a separate runtime:

• keep an explicit, reviewable governance profile in .github/harness/governance-profile.yaml
• support governance modes:
  • core for minimal low-risk work
  • standard as the default mode for routine repo work
  • enhanced for multi-agent, deployment, or broad refactor work
• prefer verifier-first governance:
  • parse and validate the proposed action
  • classify risk
  • check ownership and permission
  • execute the smallest useful change
  • sanitize outputs and context
  • append an audit trail
• record human-readable summaries in memory/log.md and machine-readable provenance in memory/audit-log.jsonl
• use a critic-refiner loop for harness maintenance:
  • generate the smallest candidate patch
  • evaluate it with just harness-check and route-specific validation
  • refine weak parts instead of rewriting the whole harness
• keep stronger blocking behavior narrow and explicit; reserve it for dangerous or policy-forbidden actions

Environment-Tuned Harnessing

Apply the useful parts of environment tuning to harness maintenance:

• do not rely on a single binary "harness exists or not" judgment
• use staged scaffold or update work so the harness can improve from simple to complex without collapsing into a rewrite
• prefer actionable corrective feedback over vague failure notes
• keep corrective feedback pedagogical and non-leaky:
  • identify root cause
  • reveal violated rule or missing prerequisite
  • suggest the next class of action
  • do not prescribe the full solution when exploration still matters
• use fine-grained progress checks so partial harness health is visible before the full stack is complete

When the harness is weak, tune the environment around the agent first:

• improve prompts, checks, hooks, reports, and memory cues before adding more top-level instruction mass
• turn repeated dead ends into better diagnostics, examples, or checklists instead of repeating the same guidance in chat

Implicit Context Update Model

Apply the useful parts of in-context learning theory to harness design:

• treat each new harness artifact as a small context update, not a reason to rewrite the whole harness
• prefer low-rank context patches:
  • a narrow scoped instruction
  • a short prompt example
  • a small playbook entry
  • a targeted agent overlay
• assume examples and small reference patterns can shift agent behavior disproportionately; keep a few high-quality examples and avoid noisy prompt accumulation
• prefer retrieving and composing the smallest useful context slice for the task instead of loading every layer at once

Before Editing

1. Run just harness-snapshot and summarize the current harness state.
2. Inspect:
   • .github/copilot-instructions.md
   • AGENTS.md
   • .github/instructions/
   • .github/prompts/
   • .github/agents/
   • .github/hooks/
   • .github/harness/
   • memory/
   • .github/skills/ and .sea/skills/
3. Classify the work as:
   • bootstrap: expected layers are missing or ad hoc
   • update: the harness exists but needs tightening or completion
4. Extract existing authority order, validation commands, and memory conventions from the repo before inventing new ones.

Bootstrap Workflow

1. Preserve useful existing files and patterns.
2. Use a staged rollout when the harness is missing or weak:
   • stage 1: top-layer correctness and routing
   • stage 2: actionable prompts, reporting, and memory hygiene
   • stage 3: scoped rules, stack specialization, and richer reuse
   • stage 4: alignment, de-scaffolding, and strict validation
3. Keep .github/copilot-instructions.md short. It should contain the stable operating contract, validation tiers, and a project overlay.
4. Keep AGENTS.md index-like. It should define instruction priority, routing, task entrypoints, handoff rules, memory update triggers, and done criteria.
5. Create or update scoped .github/instructions/*.instructions.md files only where real scoping helps.
6. Create or update .github/prompts/*.prompt.md files for named manual workflows. Include concise examples only when they materially improve behavior.
7. Create or update .github/agents/*.agent.md files for role overlays and handoffs.
8. Update canonical skills in .sea/skills and preserve .github/skills discovery through the mirror.
9. Add or update .github/hooks/*.json only for explicit, safe, reviewable lifecycle automation.
10. Create or update .github/harness/governance-profile.yaml when explicit governance mode, verifier strategy, or reviewable pipeline settings would help.
11. Create or update .github/harness/runtime-harness.yaml and .github/harness/runtimes/*.yaml when runtime roles, handoffs, or external-runtime integration boundaries need to be explicit.
12. Create or update memory/* for volatile task context using Markdown, YAML, JSON, and JSONL where each format fits best. Reuse existing memory surfaces for lessons, reflections, and history before introducing new state files.
13. Leave the harness easier to navigate than you found it.
14. When scaffolding missing base files, start from the bundled templates in assets/templates/ and then adapt them to the repo instead of inventing fresh structure each time.

Required Router Surface

Ensure the harness router can explicitly handle these work modes:

• architecture synthesis
• architecture decision drafting
• product and solution spec drafting
• conversation-to-spec
• case orchestration
• cognitive artifacting
• generator-first change routing
• generator authoring
• generator validation
• post-pipeline last-mile generation
• SEA-DSL authoring
• semantic anchoring
• coherence measurement
• harness bootstrap
• harness audit
• runtime harness governance

The router should expose:

• mode classification
• prompt entrypoint
• agent stance
• scoped-rule attachment
• validation command
• handoff rules between adjacent modes
• runtime-role boundaries where external runtimes are part of the operating model

External Pack Assimilation

When integrating a plugin or external agent pack:

1. Deconstruct it into primitives:
   • prompts or commands
   • role overlays
   • hooks
   • state artifacts
   • deterministic scripts
2. Map each primitive onto existing harness layers before adding anything:
   • command -> prompt or just recipe
   • evaluator or reflector -> agent overlay
   • plugin state -> memory/*
   • reusable procedure -> skill or script
3. Prefer structural mapping over tree mirroring.
4. Preserve only the pieces that improve harness coherence, diagnostics, or maintainability.
5. If the pack duplicates existing memory concerns, map them instead of cloning them.

For cdaa-coherence, prefer this mapping:

• plugin command cdaa-measure -> just harness-coherence and .github/prompts/coherence-measure.prompt.md
• evaluator and reflector -> .github/agents/coherence-evaluator.agent.md and .github/agents/coherence-reflector.agent.md
• CURRENT_STATE.md -> memory/coherence-current-state.md
• OPEN_BREAKS.md -> memory/coherence-open-breaks.md
• LESSONS_LEARNED.md -> existing memory/playbook.md
• REFLECTION_LOG.md -> existing memory/reflections.md
• EXECUTION_HISTORY.md -> existing memory/log.md
• plugin measurement output -> memory/coherence-report.json

For these imported skill packs, prefer this mapping:

• conversational-development -> scoped instruction plus conversation-to-spec prompt
• sea-conversation-to-spec -> conversation-to-spec prompt plus existing ADR/PRD/SDS prompts
• sea-domain-expert-guide -> domain-expert scoped instruction plus conversation-to-spec and cognitive-artifact overlays
• case-management -> case-orchestration prompt plus Agent Orchestrator
• pm-agent-orchestration -> Agent Orchestrator routing and case-orchestration prompt
• cognitive-artifacts-builder -> cognitive-artifact prompt and optional CADSL helper scripts when justified
• sea-generator-first -> generator-first prompt plus generator-first scoped instruction
• generator-builder -> generator-builder prompt plus canonical skill
• generator-validate -> generator-validate prompt plus canonical skill
• sea-last-mile -> last-mile prompt plus canonical skill
• sea-handler-gen -> handler-generation prompt plus canonical skill
• sea-dsl-authoring -> dsl-authoring prompt plus canonical skill
• semantic-anchoring -> semantic-anchoring prompt plus canonical skill
• sea-release -> deploy-release prompt plus canonical skill

Maintenance Operations

Support these three operations:

Ingest

• inspect current repo and harness state
• update the maintained harness and memory layer
• append a short entry to memory/log.md
• append a structured event to memory/audit-log.jsonl
• place newly learned but not-yet-stable lessons in memory/reflections.md
• record partial progress, not only the final result:
  • top layer
  • routing
  • prompts and agents
  • memory
  • validation
• use just harness-bootstrap-report "summary" --reflection "..." [--note "..."] [--pattern "..."] to record the run

Query

• answer using the maintained harness, index, and memory structure
• prefer memory/index.md as the human navigation layer and memory/index.json as the machine-friendly registry
• file especially useful distilled answers back into memory or docs when justified
• prefer memory/playbook.md over raw reflections when choosing durable guidance

Lint

• run the harness lint scripts
• detect contradictions, stale context, orphaned files, excessive top-layer bloat, and misassigned responsibilities
• detect missing governance profile details, missing mode selection, and missing machine-readable provenance
• detect runtime role drift, unclear handoffs, and runtime-local behavior that should be governed by the repo harness
• detect vague corrective feedback and replace it with actionable but non-leaky guidance when useful
• detect parallel state systems introduced by imported plugins or packs and collapse them back into the harness memory model
• recommend or apply the smallest useful fix
• reflect on lint output before curating changes into durable layers
• after a meaningful lint-driven improvement, record it with just harness-lint-report "summary" --reflection "..." [--note "..."]

Generation, Reflection, Curation

Generation

• create candidate instructions, prompts, agents, hooks, or memory updates
• prefer incremental edits over whole-file rewrites

Reflection

• use natural execution feedback from:
  • just harness-check
  • helper lint scripts
  • bootstrap or audit runs
  • real user interactions with the harness
• prefer reflections that explain:
  • what failed
  • what signal was missing
  • what small environment or context change fixed it
• store distilled feedback in memory/reflections.md

Curation

• promote stable patterns into memory/playbook.md
• move curated patterns into durable layers using the promotion protocol below
• avoid promoting one-off or task-local notes
• use just harness-report <action> "summary" --pattern "Pattern Title" when a reflection has become durable enough for the playbook

Missing Details To Add When Absent

If the current harness does not already encode these clearly, add them in the correct layer:

Authority hierarchy

• direct user request
• safety and security constraints
• repo operating instructions
• architecture and ADR docs
• working memory files
• local code patterns and conventions

Inspect vs ask

• inspect first
• ask only when goals are unclear, tradeoffs are value-based, credentials are missing, or ambiguity materially changes implementation

Edit discipline

• prefer small, reversible diffs
• preserve existing patterns unless intentionally migrating
• avoid unrelated refactors unless necessary
• explain broad or high-impact changes before making them

Validation protocol

• define validation tiers for small local changes, shared interface changes, build/tooling changes, and cross-package or schema changes
• say exactly what remains unverified when validation cannot be run

Definition of done

• the requested change is implemented or the blocking ambiguity is explicit
• relevant validation ran or was clearly deferred
• assumptions are stated
• docs updated if behavior changed
• memory updated if useful
• the next move is clear

Memory protocol

• define which memory files exist
• define when each one should be updated
• define staleness policy
• require last-updated metadata where the format supports it
• add index.md, index.json, and append-only log.md
• keep examples and notes sparse but high-signal so each addition acts like a useful context patch rather than noise

Promotion protocol

• repeated stable rule -> instructions
• repeated workflow -> prompt
• repeated role behavior -> agent
• repeated rich reusable workflow -> skill
• repeated volatile note -> promote into durable docs or instructions when justified
• repeated curated harness strategy -> playbook

File Responsibilities

.github/copilot-instructions.md

• keep it thin
• make it a stable operating contract
• include inspect-before-ask behavior
• include edit discipline
• include validation tiers
• include definition of done
• include a small project overlay
• do not dump large architecture prose into it

AGENTS.md

• make it the routing and priority file
• define which sources win when they conflict
• route feature, debug, refactor, architecture, tooling, and harness work
• define memory update triggers and staleness policy
• define which docs matter for which task type
• point outward to deeper context instead of restating it

.github/instructions/*.instructions.md

• use for scoped or path-specific rules
• keep each file narrow
• add applyTo only when automatic attachment is useful
• conversational evidence and confirmation rules fit naturally here

.github/prompts/*.prompt.md

• use for user-invoked slash workflows
• keep them concise and task-shaped
• prefer prompts as entrypoints into richer skills or agents
• coherence measurement and other independent evaluators belong here, not in top-level instructions
• architecture synthesis, conversation-to-spec, case orchestration, and cognitive artifacting should exist here when the repo repeatedly uses those work modes

.github/agents/*.agent.md

• use for role overlays
• keep the persona focused
• encode handoff or specialization boundaries, not giant task manifests
• prefer short specialist overlays such as architect, debugger, reviewer, test-writer, or migration-planner when repeated use justifies them
• independent evaluator and slow-layer reflector roles fit naturally here

.github/hooks/*.json

• use for deterministic lifecycle automation
• favor safe checks, context injection, and protection of critical zones
• avoid heavy or surprising commands in hooks

.github/harness/*.yaml

• use for explicit governance settings and runtime role boundaries
• keep runtime role definitions, handoffs, and control-plane integration assumptions reviewable
• do not hide cross-runtime authority boundaries inside prompts or memory files

memory/*

• use for current task state, decisions, open questions, glossary, machine-readable active context, and structured indexes
• keep it volatile, concise, and easy to refresh
• keep it file-based in Markdown, YAML, JSON, and JSONL
• do not let it become duplicate docs, duplicate source code, or duplicate architecture prose
• maintain both index.md and index.json
• keep log.md append-only as a chronological maintenance record
• keep audit-log.jsonl append-only as the machine-readable provenance trail
• keep playbook.md as curated durable harness strategy
• keep reflections.md as pre-curation execution feedback
• for coherence packs, keep only explicit state deltas such as current coherence state and open breaks; reuse existing playbook, reflections, and log for lessons and history

Stack Specialization

For this repository, specialize the harness for:

• Nx project discovery and affected-task validation
• pnpm workspace task execution
• uv and Python environment flows
• cargo for Rust surfaces
• just as the shared task runner
• mise and devbox environment conventions
• GitHub Actions and CI-mirror commands

Prefer existing repo entrypoints such as just, pnpm exec nx, uv, and cargo over ad hoc commands.

Lean Expansion Set

Start with this minimal useful stack before expanding further:

• .github/copilot-instructions.md
• AGENTS.md
• memory/current-task.md
• memory/decisions.md
• memory/open-questions.md
• memory/glossary.md
• memory/active-context.yaml
• .github/prompts/implement.prompt.md
• .github/prompts/debug.prompt.md
• .github/prompts/refactor.prompt.md
• .github/prompts/review.prompt.md
• .github/prompts/write-adr.prompt.md
• .github/prompts/review-diff.prompt.md
• .github/prompts/architecture-synthesis.prompt.md
• .github/prompts/conversation-to-spec.prompt.md
• .github/prompts/case-orchestration.prompt.md
• .github/prompts/cognitive-artifact.prompt.md
• .github/prompts/deploy-release.prompt.md
• .github/prompts/coherence-measure.prompt.md
• .github/prompts/generator-first.prompt.md
• .github/prompts/generator-builder.prompt.md
• .github/prompts/generator-validate.prompt.md
• .github/prompts/last-mile.prompt.md
• .github/prompts/handler-generation.prompt.md
• .github/prompts/dsl-authoring.prompt.md
• .github/prompts/semantic-anchoring.prompt.md
• .github/instructions/conversation-to-spec.instructions.md
• .github/instructions/domain-expert.instructions.md
• .github/instructions/generator-first.instructions.md
• .github/harness/governance-profile.yaml
• .github/harness/runtime-harness.yaml
• .github/harness/runtimes/zeroclaw.yaml
• .github/harness/runtimes/opencode.yaml
• .github/harness/runtimes/goose.yaml
• .github/harness/runtimes/thoth-legacy.yaml
• .github/agents/architecture-synthesis.agent.md
• .github/agents/adr-thought-partner.agent.md
• .github/agents/prd-thought-partner.agent.md
• .github/agents/sds-thought-partner.agent.md
• .github/agents/agent-orchestrator.agent.md
• .github/agents/coherence-evaluator.agent.md
• .github/agents/coherence-reflector.agent.md
• short role overlays only if repeated use justifies them

Design Rules

• prefer progressive disclosure over context dumping
• separate stable versus volatile context
• prefer small, reviewable edits over broad resets
• preserve existing good structure
• if a layer is already working, do not replace it just to make the harness more uniform
• prefer staged improvement over all-at-once rewrites
• prefer actionable feedback over vague failure summaries
• preserve exploration space when adding hints or examples
• treat each new context addition as a small behavior-shaping patch; prune noisy or redundant additions

Output Contract

End with:

## Harness Status
- Mode: bootstrap|update
- Preserved: [...]
- Created: [...]
- Updated: [...]

## Assumptions
- [...]

## Open Questions
- [...]

## Recommended Next Validation
- just harness-check
- [other relevant command]

References

Load references/harness-layout.md for:

• starter file responsibilities
• manual versus auto-load choices
• hook guidance
• validation checklist
• recommended implementation details that are easy to miss

Use the bundled templates in assets/templates/ as the default scaffold source for:

• .github/copilot-instructions.md
• AGENTS.md
• memory/current-task.md
• memory/decisions.md
• memory/open-questions.md
• memory/glossary.md
• memory/active-context.yaml
• memory/index.json
• memory/playbook.md
• memory/reflections.md
• .github/prompts/implement.prompt.md
• .github/prompts/debug.prompt.md
• .github/prompts/refactor.prompt.md
• .github/prompts/review.prompt.md
• .github/agents/debugger.agent.md
• .github/agents/reviewer.agent.md
• memory/index.md
• memory/log.md
• .github/prompts/write-adr.prompt.md
• .github/prompts/review-diff.prompt.md
• .github/prompts/coherence-measure.prompt.md
• .github/prompts/architecture-synthesis.prompt.md
• .github/prompts/conversation-to-spec.prompt.md
• .github/prompts/case-orchestration.prompt.md
• .github/prompts/cognitive-artifact.prompt.md
• .github/prompts/deploy-release.prompt.md
• .github/prompts/generator-first.prompt.md
• .github/prompts/generator-builder.prompt.md
• .github/prompts/generator-validate.prompt.md
• .github/prompts/last-mile.prompt.md
• .github/prompts/handler-generation.prompt.md
• .github/prompts/dsl-authoring.prompt.md
• .github/prompts/semantic-anchoring.prompt.md
• .github/agents/coherence-evaluator.agent.md
• .github/agents/coherence-reflector.agent.md
• .github/instructions/conversation-to-spec.instructions.md
• .github/instructions/domain-expert.instructions.md
• .github/instructions/generator-first.instructions.md
• .github/harness/governance-profile.yaml
• .github/harness/runtime-harness.yaml
• .github/harness/runtimes/zeroclaw.yaml
• .github/harness/runtimes/opencode.yaml
• .github/harness/runtimes/goose.yaml
• .github/harness/runtimes/thoth-legacy.yaml