Coverage for src/governed_harness/embedded/skills.py: 85%
16 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Skill files that teach an agent session the governed flow (#56).
3``harness init --agent-skills`` writes the same skill for Claude Code
4(``.claude/skills/harness/SKILL.md``) and Codex (``.codex/skills/harness/SKILL.md``). A skill is
5instructions, not authority: the harness still enforces every gate, digest and decision, and
6the skill tells the agent which steps belong to a person."""
8from __future__ import annotations
10from pathlib import Path
12SKILL_PATHS: tuple[str, ...] = (
13 ".claude/skills/harness/SKILL.md",
14 ".codex/skills/harness/SKILL.md",
15)
17SKILL_TEXT = """\
18---
19name: harness
20description: Drive a governed change with the Governed Agent Harness. Use when the user asks for a governed, verified or approved change, or when the repository has .harness/project.yaml.
21---
23# Governed change with the harness
25The harness governs the change; you implement it in this session. Gates, digests and human
26decisions are enforced by the harness, not by you.
28## Flow
301. Write the task as a task document (title, intent, requirements, acceptance criteria with an
31 observable result, constraints) with `implementation: {mode: none}`, and create it:
32 MCP tool `harness_task_create`, or `harness task create --file task.yaml`.
332. Start the run with the session provider: `harness_run_start` (provider `session`), or
34 `harness run start --task <taskId> --provider session`.
353. If INTENT asks questions (exit 6, `Intent needs clarification`), show them to the person
36 (`harness_task_questions`), ask for their answers and relay their exact words with
37 `harness_task_clarify`. Never answer for the person. Then `harness_run_continue`.
384. If a phase waits for a person (acceptance tests, a plan, the architecture), tell the person
39 the command the status shows (`harness acceptance decide`, `harness plan decide`,
40 `harness architecture decide`). Do not run it yourself.
415. When the run waits in IMPLEMENTATION, implement in the workspace. Follow the standards cards
42 (`harness_standards` with the files you touch) and the architecture layers. Run
43 `harness_check` (or `harness check --run <runId>`) until it passes, then
44 `harness_run_continue`.
456. If VERIFICATION or the review reports findings (`harness_status`), fix them in the workspace
46 and continue again.
477. When the run reaches DECISION (exit code 4), stop. Show the person `harness review --run
48 <runId>`; the person decides with `harness gate decide`. You never decide a gate.
50## Rules
52- Do not weaken tests, thresholds or checks to make them pass; do not edit `.harness/`.
53- Clean up only the code you touch; no unrelated refactors or reformatting.
54- With TDD the tests you add must fail before your change: write them first.
55- With BDD the approved feature files are frozen: write step definitions, not new scenarios.
57## Without the MCP server
59Every tool has a command: `harness status`, `harness inbox`, `harness task create`,
60`harness task questions`, `harness task clarify`, `harness run start`, `harness run continue`,
61`harness check`, `harness review`, `harness standards show --file <path>`.
62"""
65def write_agent_skills(workspace: Path, *, force: bool = False) -> list[dict[str, str]]:
66 """Write the skill files; an existing file is kept unless ``force``."""
67 written: list[dict[str, str]] = []
68 for relative in SKILL_PATHS:
69 target = workspace / relative
70 if target.exists() and not force: 70 ↛ 71line 70 didn't jump to line 71 because the condition on line 70 was never true
71 written.append({"path": relative, "status": "KEPT"})
72 continue
73 target.parent.mkdir(parents=True, exist_ok=True)
74 target.write_text(SKILL_TEXT, encoding="utf-8")
75 written.append({"path": relative, "status": "WRITTEN"})
76 return written
79__all__ = ["SKILL_PATHS", "SKILL_TEXT", "write_agent_skills"]