Repo Bootstrap

Repo Bootstrap

Create and maintain a .harness/ workspace in the repository root so future turns keep stable project memory, structured plan state, and reviewable execution artifacts.

This skill now uses .harness/state.json as a local machine-readable source of truth. The five markdown files are rendered from that state so the agent can keep updating them without losing prior knowledge.

When To Use It

• First-time repository bootstrap
• Ongoing work where the agent should persist memory across turns
• Non-trivial implementation that needs plan/checklist tracking
• Periodic repo-wiki refresh after architecture or workflow discovery
• Long-running sessions where prompt history and decisions should survive context-window loss

Core Model

The durable memory model has two layers:

1. .harness/state.json
   • structured source of truth for current memory, prompt log, repo facts, plan, and checklist state
   • preserves rolling history and allows deterministic markdown regeneration
2. Rendered markdown views
   • .harness/memory.md
   • .harness/prompt.md
   • .harness/repowiki.md
   • .harness/plan.md
   • .harness/checklist.md

/.harness/ must remain gitignored.

Quick Start

1. Resolve repository root.
2. Run a bootstrap or sync command:

Claude Code:

bashCopy code
python3 ~/.claude/skills/repo-bootstrap/scripts/init_docs.py \
  --repo-root <repo-root> \
  --latest-prompt "Summarize and improve this repo bootstrap skill." \
  --intent "Persist durable repo memory and update the harness docs." \
  --objective "Upgrade repo-bootstrap to support rolling updates." \
  --workstream "skill enhancement" \
  --work-summary "Synced harness state for the current task." \
  --next-action "Run verification"

Codex:

bashCopy code
python3 "$CODEX_HOME/skills/repo-bootstrap/scripts/init_docs.py" \
  --repo-root <repo-root> \
  --latest-prompt "Summarize and improve this repo bootstrap skill." \
  --intent "Persist durable repo memory and update the harness docs." \
  --objective "Upgrade repo-bootstrap to support rolling updates." \
  --workstream "skill enhancement" \
  --work-summary "Synced harness state for the current task." \
  --next-action "Run verification"

3. For richer updates, write a JSON payload and pass --context-file:

Claude Code:

bashCopy code
python3 ~/.claude/skills/repo-bootstrap/scripts/init_docs.py \
  --repo-root <repo-root> \
  --context-file /tmp/harness-context.json

Codex:

bashCopy code
python3 "$CODEX_HOME/skills/repo-bootstrap/scripts/init_docs.py" \
  --repo-root <repo-root> \
  --context-file /tmp/harness-context.json

4. Confirm these files exist:
   • .harness/state.json
   • .harness/memory.md
   • .harness/prompt.md
   • .harness/repowiki.md
   • .harness/plan.md
   • .harness/checklist.md
5. Confirm .gitignore contains /.harness/.

Required Turn Workflow

Apply this workflow every time the skill is invoked.

1. Read .harness/memory.md and .harness/prompt.md before analysis.
2. For code or architecture tasks, also read .harness/repowiki.md before planning.
3. Before finishing the turn, sync the latest task context back into .harness/state.json.
4. Let the script re-render the five markdown files from state.
5. If facts changed, update repowiki.md through the structured state instead of editing only the markdown view.

The skill is only doing its job if the state is refreshed continuously. Bootstrap alone is not enough.

Non-Negotiable Rules

1. .harness/state.json is the canonical local memory store.
2. memory.md and prompt.md must be refreshed on every invocation.
3. repowiki.md must be refreshed whenever repository facts evolve, or at minimum receive a review entry.
4. plan.md and checklist.md must stay aligned through shared step IDs or explicit mapping.
5. /.harness/ must stay ignored in .gitignore.
6. Do not wipe history just to keep docs tidy; summarize or trim old entries instead.
7. Do not rely on placeholder-only content after bootstrap.

First-Run Baseline Expectations

The first run should produce useful baseline content automatically:

• repo name and summary from README when available
• stack/toolchain guesses from manifests and lockfiles
• detected run/build/test/lint commands
• top-level directory map placeholders with concrete paths
• initial memory objective, risks, next actions, and decisions
• initial prompt record even when no explicit prompt was supplied

Unknown facts are allowed, but they must be framed as explicit gaps or discovery actions, not empty stubs.

Structured Update Payload

The script accepts structured context through --context-file or --context-json.

Supported top-level fields:

• latest_prompt
• prompt_summary
• intent
• constraints
• success_criteria
• requested_output_format
• objective
• definition_of_done
• workstream
• why_now
• work_summary
• repo_facts
• assumptions
• decisions
• blockers
• risks
• open_questions
• next_actions
• repo_name
• repo_summary
• repo_purpose
• stakeholders
• non_goals
• directory_map
• architecture
• data_flow
• required_env_vars
• test_strategy
• deployment_notes
• observability_notes
• security_notes
• known_gaps
• repowiki_review
• plan
• checklist

Recommended shapes:

• decisions: array of {summary, reason, tradeoff}
• blockers: array of {item, owner, next_action}
• risks: array of {item, impact, mitigation}
• open_questions: array of {question, discovery_action, expected_source}
• plan.steps: array of {id, step, why, owner, status}
• plan.files: array of {path, change_type, purpose, linked_step}
• checklist.plan_mapping: array of {plan_step, item, status, evidence}
• checklist.files: array of {path, purpose, linked_step, status}
• checklist.validation_results: array of {check, result, notes}

If plan is present and checklist is omitted, the script auto-derives a checklist skeleton from the plan.

Five-Document Responsibility Contract

RepoWiki Depth Standard

.harness/repowiki.md must remain a practical wiki, not a summary paragraph. It should stay useful for future sessions by including:

1. repository purpose and non-goals
2. architecture notes and control/data-flow hints
3. module or directory responsibility map
4. local development commands
5. runtime/config notes
6. test strategy and quality gates
7. operational/security notes when they become known
8. known gaps and explicit discovery actions

Plan and Checklist Contract

When plan.md is active:

• record assumptions, dependencies, risks, mitigations, and rollback intent
• include explicit file-level change plans
• define validation before implementation

When checklist.md is active:

• track execution progress honestly
• include every modified file and one-line purpose
• record validation outcomes as pass, fail, skip, or pending
• stay aligned with plan step IDs

Migration Behavior

If legacy markdown files exist (from either .harness/ or the older codex/ directory) but .harness/state.json does not, the script captures those markdown files into state archives before rendering the new state-backed versions. This prevents silent knowledge loss during upgrade.

Anti-Patterns

• Running bootstrap once and never syncing again
• Editing markdown views while ignoring state.json
• Letting memory.md or prompt.md go stale
• Allowing plan.md and checklist.md to drift apart
• Replacing explicit unknowns with generic TODO-only stubs
• Removing historical context without a summary

Resources

scripts/

• scripts/init_docs.py: bootstraps and continuously syncs .harness/state.json plus the rendered markdown files.