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

1"""Skill files that teach an agent session the governed flow (#56). 

2 

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.""" 

7 

8from __future__ import annotations 

9 

10from pathlib import Path 

11 

12SKILL_PATHS: tuple[str, ...] = ( 

13 ".claude/skills/harness/SKILL.md", 

14 ".codex/skills/harness/SKILL.md", 

15) 

16 

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--- 

22 

23# Governed change with the harness 

24 

25The harness governs the change; you implement it in this session. Gates, digests and human 

26decisions are enforced by the harness, not by you. 

27 

28## Flow 

29 

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. 

49 

50## Rules 

51 

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. 

56 

57## Without the MCP server 

58 

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""" 

63 

64 

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 

77 

78 

79__all__ = ["SKILL_PATHS", "SKILL_TEXT", "write_agent_skills"]