initial commit

.agents/skills/harness-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: harness-review
+description: Review a Harness Engineering repository against its persistent rules and design docs. Use when Codex is asked to review local changes, generated phase files, or implementation output against `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/UI_GUIDE.md`, testing expectations, and Harness step acceptance criteria.
+---
+
+# Harness Review
+
+Use this skill when the user wants a repository-grounded review instead of generic commentary.
+
+## Review input set
+
+Read these first:
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/UI_GUIDE.md`
+- the changed files or generated `phases/` files under review
+
+If the user explicitly asks for delegated review, prefer the repo custom agent `harness_reviewer` or built-in read-only explorers.
+
+## Checklist
+
+Evaluate the patch against these questions:
+
+1. Does it follow the architecture described in `docs/ARCHITECTURE.md`?
+2. Does it stay within the technology choices documented in `docs/ADR.md`?
+3. Are new or changed behaviors covered by tests or other explicit validation?
+4. Does it violate any CRITICAL rule in `AGENTS.md`?
+5. Do generated `phases/` files remain self-contained, executable, and internally consistent?
+6. If the user expects verification, does `python scripts/validate_workspace.py` succeed or is the failure explained?
+
+## Output rules
+
+- Lead with findings, ordered by severity.
+- Include file references for each finding.
+- Explain the concrete risk or regression, not just the rule name.
+- If there are no findings, say so explicitly and mention residual risks or missing evidence.
+- Keep summaries brief after the findings.
+
+## Preferred review table
+
+When the user asks for a checklist-style review, use this table:
+
+| Item | Result | Notes |
+|------|------|------|
+| Architecture compliance | PASS/FAIL | {details} |
+| Tech stack compliance | PASS/FAIL | {details} |
+| Test coverage | PASS/FAIL | {details} |
+| CRITICAL rules | PASS/FAIL | {details} |
+| Build and validation | PASS/FAIL | {details} |
+
+## What not to do
+
+- Do not approve changes just because they compile.
+- Do not focus on style-only issues when correctness, architecture drift, or missing validation exists.
+- Do not assume a passing hook means the implementation is acceptable; review the actual diff and docs.

.agents/skills/harness-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Harness Review"
+  short_description: "Review changes against Harness project rules"
+  default_prompt: "Use Harness review to check architecture, tests, and rules."

.agents/skills/harness-workflow/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: harness-workflow
+description: Plan and run the Harness Engineering workflow for this repository. Use when Codex needs to read `AGENTS.md` and `docs/*.md`, discuss implementation scope, draft phase plans, or create/update `phases/index.json`, `phases/{phase}/index.json`, and `phases/{phase}/stepN.md` files for staged execution.
+---
+
+# Harness Workflow
+
+Use this skill when the user is working in the Harness template and wants structured planning or phase-file generation.
+
+## Workflow
+
+### 1. Explore first
+
+Read these files before proposing steps:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/UI_GUIDE.md`
+
+If the user explicitly asks for parallel exploration, use built-in Codex subagents such as `explorer`, or the repo-scoped custom agent `phase_planner`.
+
+### 2. Discuss before locking the plan
+
+If scope, sequencing, or architecture choices are still ambiguous, surface the decision points before creating `phases/` files.
+
+### 3. Design steps with strict boundaries
+
+When drafting a phase plan:
+
+1. Keep scope minimal. One step should usually touch one layer or one module.
+2. Make each step self-contained. Every `stepN.md` must work in an isolated Codex session.
+3. List prerequisite files explicitly. Never rely on "as discussed above".
+4. Specify interfaces or invariants, not line-by-line implementations.
+5. Use executable acceptance commands, not vague success criteria.
+6. Write concrete warnings in "do not do X because Y" form.
+7. Use kebab-case step names.
+
+## Files to generate
+
+### `phases/index.json`
+
+Top-level phase registry. Append to `phases[]` when the file already exists.
+
+```json
+{
+  "phases": [
+    {
+      "dir": "0-mvp",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+- `dir`: phase directory name.
+- `status`: `pending`, `completed`, `error`, or `blocked`.
+- Timestamp fields are written by `scripts/execute.py`; do not seed them during planning.
+
+### `phases/{phase}/index.json`
+
+```json
+{
+  "project": "<project-name>",
+  "phase": "<phase-name>",
+  "steps": [
+    { "step": 0, "name": "project-setup", "status": "pending" },
+    { "step": 1, "name": "core-types", "status": "pending" },
+    { "step": 2, "name": "api-layer", "status": "pending" }
+  ]
+}
+```
+
+- `project`: from `AGENTS.md`.
+- `phase`: directory name.
+- `steps[].step`: zero-based integer.
+- `steps[].name`: kebab-case slug.
+- `steps[].status`: initialize to `pending`.
+
+### `phases/{phase}/stepN.md`
+
+Each step file should contain:
+
+1. A title.
+2. A "read these files first" section.
+3. A concrete task section.
+4. Executable acceptance criteria.
+5. Verification instructions.
+6. Explicit prohibitions.
+
+Recommended structure:
+
+```markdown
+# Step {N}: {name}
+
+## Read First
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- {files from previous steps}
+
+## Task
+{specific instructions}
+
+## Acceptance Criteria
+```bash
+python scripts/validate_workspace.py
+```
+
+## Verification
+1. Run the acceptance commands.
+2. Check AGENTS and docs for rule drift.
+3. Update the matching step in phases/{phase}/index.json:
+   - completed + summary
+   - error + error_message
+   - blocked + blocked_reason
+
+## Do Not
+- {concrete prohibition}
+```
+```
+
+## Execution
+
+Run the generated phase with:
+
+```bash
+python scripts/execute.py <phase-name>
+python scripts/execute.py <phase-name> --push
+```
+
+`scripts/execute.py` handles:
+
+- `feat-{phase}` branch checkout/creation
+- guardrail injection from `AGENTS.md` and `docs/*.md`
+- accumulation of completed-step summaries into later prompts
+- up to 3 retries with prior error feedback
+- two-phase commit of code changes and metadata updates
+- timestamps such as `created_at`, `started_at`, `completed_at`, `failed_at`, and `blocked_at`
+
+## Recovery rules
+
+- If a step is `error`, reset its status to `pending`, remove `error_message`, then rerun.
+- If a step is `blocked`, resolve the blocker, reset to `pending`, remove `blocked_reason`, then rerun.

.agents/skills/harness-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Harness Workflow"
+  short_description: "Guide Codex through Harness phase planning"
+  default_prompt: "Use the Harness workflow to plan phases and step files."