@hallucination-studio/harness-engine 1.0.0 → 1.0.1

package/skills/harness-engine/scripts/harness_engine/templates.py

@@ -0,0 +1,124 @@
+from .common import *
+
+def make_default_answers(analysis):
+    repo_name = analysis["project_name"]
+    frameworks = ", ".join(analysis["frameworks"]) or "Unknown"
+    style_files = analysis.get("frontend_style_files") or []
+    style_file_summary = ", ".join(style_files) if style_files else "No shared style, theme, token, or component style files detected yet."
+    has_frontend = analysis["has_frontend"]
+    frontend_scope = (
+        "User-facing or operator-facing frontend work is expected."
+        if has_frontend
+        else "No clear frontend surface was detected yet. Update this if a UI emerges."
+    )
+    frontend_validation_loop = (
+        "- Run local UI changes in a browser.\n"
+        "- Check desktop and mobile layouts when relevant.\n"
+        "- Verify key flows, empty states, and failure states.\n"
+        "- Record reusable UI findings in `docs/design-docs/`."
+        if has_frontend
+        else "- Validate interface changes in the relevant local runtime.\n"
+        "- Verify key flows, empty states, failure states, and cleanup behavior where applicable.\n"
+        "- Record reusable interface findings in `docs/design-docs/`."
+    )
+    defaults = {
+        "project_name": repo_name,
+        "project_summary": f"Summarize the main outcome that {repo_name} should deliver.",
+        "primary_users": "Describe the primary users, operators, or internal teams.",
+        "deployment_targets": "Describe the main runtime or deployment targets.",
+        "product_domain": "Describe the product domain in one line.",
+        "reliability_targets": "Describe uptime, failure tolerance, recovery expectations, and required validation loops.",
+        "security_constraints": "Describe auth, secrets, compliance, sensitive data, and review constraints.",
+        "frontend_stack_notes": (
+            f"Detected frameworks: {frameworks}. Describe UX expectations, supported environments, and review rules."
+            if has_frontend
+            else "No frontend detected. Replace this if the repo includes UI work."
+        ),
+        "design_style_direction": (
+            "Describe the concrete visual direction before major UI work: reference point, mood, density, palette, typography, component shape, and hard don'ts."
+            if has_frontend
+            else "No frontend detected."
+        ),
+        "existing_frontend_style_notes": style_file_summary,
+        "quality_focus": "List the product areas and architectural layers that deserve the strictest quality bar.",
+        "frontend_scope": frontend_scope,
+        "frontend_validation_loop": frontend_validation_loop,
+    }
+    return defaults
+
+
+def fill_template(template, answers, analysis):
+    merged = {}
+    merged.update(make_default_answers(analysis))
+    merged.update(answers)
+    merged.update(
+        {
+            "marker": MANAGED_MARKER,
+            "languages": ", ".join(analysis["languages"]) or "Unknown",
+            "package_managers": ", ".join(analysis["package_managers"]) or "Unknown",
+            "frameworks": ", ".join(analysis["frameworks"]) or "Unknown",
+        }
+    )
+    return template.format(**merged)
+
+
+def ensure_parent(path):
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def is_managed_text(text):
+    return text.startswith(MANAGED_MARKER) or (
+        text.startswith("---") and "\nsource: harness-engine-template\n" in text[:500]
+    )
+
+
+def is_obsolete_managed_text(text):
+    return any(text.startswith(marker) for marker in OBSOLETE_MANAGED_MARKERS)
+
+
+def is_harness_owned_text(text):
+    return is_managed_text(text) or is_obsolete_managed_text(text)
+
+
+def should_write(path, refresh_managed, force):
+    if not path.exists():
+        return True
+    if force:
+        return True
+    try:
+        is_managed = is_harness_owned_text(path.read_text())
+    except UnicodeDecodeError:
+        return False
+    if refresh_managed and is_managed:
+        return True
+    return False
+
+
+def write_scaffold(repo, analysis, answers, refresh_managed=False, force=False):
+    written = []
+    created = []
+    refreshed = []
+    skipped = []
+    all_templates = {}
+    all_templates.update(ROOT_FILES)
+    all_templates.update(DOC_FILES)
+    if analysis["has_frontend"]:
+        all_templates.update(FRONTEND_DOC_FILES)
+
+    for relative_path, template in all_templates.items():
+        target = repo / relative_path
+        existed = target.exists()
+        if should_write(target, refresh_managed, force):
+            ensure_parent(target)
+            content = fill_template(template, answers, analysis)
+            target.write_text(content)
+            written.append(relative_path)
+            if existed:
+                refreshed.append(relative_path)
+            else:
+                created.append(relative_path)
+        else:
+            skipped.append(relative_path)
+    return written, skipped, created, refreshed
+
+

package/skills/harness-engine/scripts/manage_harness.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+
+from pathlib import Path
+import sys
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+from harness_engine.cli import main
+
+
+if __name__ == "__main__":
+    main()

package/skills/harness-repo-bootstrap/SKILL.md

@@ -1,68 +0,0 @@
----
-name: harness-repo-bootstrap
-description: Bootstrap or refresh an advanced harness-engineering repository shape for Codex-driven projects. Use when Codex needs to analyze a repository, ask the human to confirm high-impact product and architecture facts, and then create or update AGENTS.md, architecture docs, policy docs, plan folders, reference folders, and SOP-backed starter files for the repository.
----
-
-# Harness Repo Bootstrap
-
-Run the packaged script to inspect the target repository before editing files. Use the generated analysis to decide what to ask the human, what durable knowledge is missing from the repo, and which execution-plan and SOP files must be created or updated.
-
-## Workflow
-
-1. Run `python3 scripts/manage_harness.py analyze --repo <target-repo> --output <analysis.json>`.
-2. Read `analysis.json`.
-3. Ask the human only the unresolved, high-impact questions from `human_confirmations`.
-4. Run `python3 scripts/manage_harness.py sample-answers --analysis <analysis.json> --output <answers.json>`.
-5. Fill the placeholders in `answers.json` from the repository and the human's confirmed answers.
-6. Run one of:
-   - `python3 scripts/manage_harness.py init --repo <target-repo> --answers <answers.json>`
-   - `python3 scripts/manage_harness.py update --repo <target-repo> --answers <answers.json>`
-7. If the task is multi-step, run `python3 scripts/manage_harness.py plan-start --repo <target-repo> --slug <task-name> --goal "<goal>"`.
-8. If you learn durable facts during the work, run `python3 scripts/manage_harness.py knowledge-log --repo <target-repo> --plan <plan-file> --fact "<fact>" --destination <durable-doc>` and keep the returned `id`.
-9. Before closing the task, write those facts into their durable docs.
-10. Run `python3 scripts/manage_harness.py knowledge-mark-written --repo <target-repo> --plan <plan-file> --id <knowledge-id> --evidence "<text already in durable doc>"`; use `--append` only when the exact fact should be appended mechanically.
-11. Close the plan with `python3 scripts/manage_harness.py plan-close --repo <target-repo> --plan <plan-file> --summary "<summary>"`.
-12. Before handoff, run `python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py check --repo <target-repo>` from an installed target repository.
-13. After changing this skill, run `python3 evals/run_evals.py` and iterate until it passes.
-
-## Reading Order
-
-- Read [references/workflow.md](references/workflow.md) first for the operating model and question policy.
-- Read [references/file-map.md](references/file-map.md) when deciding which generated file to update.
-- Read [references/question-catalog.md](references/question-catalog.md) when the analysis surfaces ambiguous product, security, reliability, or frontend facts.
-- Read [references/knowledge-capture.md](references/knowledge-capture.md) when you discover facts that should survive chat history.
-- Read [references/exec-plans.md](references/exec-plans.md) before planning or updating any multi-step work.
-- Read [references/sop-index.md](references/sop-index.md) to choose the right SOP for architecture, UI validation, observability, or knowledge capture work.
-- Read [references/template-policy.md](references/template-policy.md) before overwriting existing files.
-- Read [references/evaluation-loop.md](references/evaluation-loop.md) before changing the skill, templates, scripts, or policy references.
-
-## Command Rules
-
-- Prefer `analyze` before `init` or `update`.
-- Prefer the draft, test, evaluate, iterate loop for changes to this skill.
-- Prefer `init` when the target repo has none of the managed files.
-- Prefer `update` when the repo already contains any managed file or a partial harness layout.
-- Do not overwrite existing files unless the human asked for it or you pass `--force`.
-- Treat the generated files as starting points. After generation, tighten them with repository-specific details instead of leaving placeholders behind.
-- Treat `docs/exec-plans/` as required state for multi-step work, not optional notes.
-- Treat `docs/sops/` as mechanical operating procedures, not background reading.
-- When you answer a question using facts that are not yet in the repo but should be reusable, write them into a durable doc before finishing.
-- Prefer `knowledge-mark-written --id ... --evidence ...` so durable docs can use natural wording instead of duplicated exact fact strings.
-- Use `plan-close` as the final guardrail so plan state and durable docs stay synchronized.
-- Use `check` as the local handoff guardrail for user repositories.
-- Run `python3 evals/run_evals.py` after skill changes and treat failures as iteration input.
-- Do not add CI to user repositories unless the human explicitly asks for it.
-
-## Output Rules
-
-- Keep `AGENTS.md` short and routing-oriented.
-- Keep durable knowledge in repo docs, not in chat-only explanations.
-- Keep plans under `docs/exec-plans/active/` and move finished plans to `docs/exec-plans/completed/`.
-- Keep generated material under `docs/generated/`.
-- Keep external, model-friendly references under `docs/references/`.
-- Keep SOPs explicit and task-triggered so the next agent can follow the same path mechanically.
-
-## Assets
-
-- Scaffold templates live under [assets/repo-template](assets/repo-template).
-- SOP starter docs live under [assets/sops](assets/sops).

package/skills/harness-repo-bootstrap/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Harness Repo Bootstrap"
-  short_description: "Scaffold advanced Codex harness docs"
-  default_prompt: "Use $harness-repo-bootstrap to analyze this repository and scaffold or refresh its advanced harness documentation."

package/skills/harness-repo-bootstrap/evals/cases.json

@@ -1,18 +0,0 @@
-[
-  {
-    "id": "empty-repo-init",
-    "description": "Empty repositories should receive the full advanced harness scaffold."
-  },
-  {
-    "id": "frontend-analysis",
-    "description": "Frontend repositories should trigger frontend-specific confirmation and policy output."
-  },
-  {
-    "id": "closed-loop-plan",
-    "description": "Execution plans should refuse to close until durable knowledge is written back."
-  },
-  {
-    "id": "preserve-unmanaged-docs",
-    "description": "Existing user-owned harness files should be skipped unless explicitly forced."
-  }
-]

package/skills/harness-repo-bootstrap/evals/run_evals.py

@@ -1,337 +0,0 @@
-#!/usr/bin/env python3
-
-import json
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-SKILL_DIR = Path(__file__).resolve().parents[1]
-MANAGER = SKILL_DIR / "scripts" / "manage_harness.py"
-
-
-def run_manager(*args, expect_success=True):
-    result = subprocess.run(
-        [sys.executable, str(MANAGER), *args],
-        text=True,
-        capture_output=True,
-        check=False,
-    )
-    if expect_success and result.returncode != 0:
-        raise AssertionError(result.stderr or result.stdout)
-    if not expect_success and result.returncode == 0:
-        raise AssertionError("Command succeeded unexpectedly")
-    if result.stdout.strip():
-        return json.loads(result.stdout)
-    return {}
-
-
-def write_answers(path, project_name="demo"):
-    answers = {
-        "project_name": project_name,
-        "project_summary": "A developer tooling project used to install and maintain Codex harness docs.",
-        "primary_users": "Codex users and maintainers",
-        "deployment_targets": "npm package and local repositories",
-        "product_domain": "developer tooling",
-        "reliability_targets": "Repeatable local commands and safe update behavior",
-        "security_constraints": "Do not write secrets or overwrite user-owned docs without consent",
-        "frontend_stack_notes": "Frontend changes require browser validation when a UI is detected",
-        "quality_focus": "installer behavior, generated docs, plan closure, and knowledge capture",
-        "frontend_scope": "No frontend unless one is detected by analysis",
-    }
-    path.write_text(json.dumps(answers, indent=2) + "\n")
-
-
-def assert_exists(repo, relative_path):
-    path = repo / relative_path
-    if not path.exists():
-        raise AssertionError(f"Expected {relative_path} to exist")
-
-
-def assert_contains(repo, relative_path, needle):
-    text = (repo / relative_path).read_text()
-    if needle not in text:
-        raise AssertionError(f"Expected {relative_path} to contain {needle!r}")
-
-
-def test_empty_repo_init(tmp_root):
-    repo = tmp_root / "empty-repo"
-    repo.mkdir()
-    answers = tmp_root / "answers.json"
-    write_answers(answers)
-
-    analysis = run_manager("analyze", "--repo", str(repo))
-    if analysis["recommended_action"] != "init":
-        raise AssertionError("Empty repo should recommend init")
-    if not analysis["missing_exec_plan_state"]:
-        raise AssertionError("Analysis should report missing exec-plan state")
-    if not analysis["missing_sops"]:
-        raise AssertionError("Analysis should report missing SOPs")
-
-    run_manager("init", "--repo", str(repo), "--answers", str(answers))
-    for relative_path in [
-        "AGENTS.md",
-        "ARCHITECTURE.md",
-        "docs/PLANS.md",
-        "docs/QUALITY_SCORE.md",
-        "docs/exec-plans/active/_template.md",
-        "docs/exec-plans/completed/README.md",
-        "docs/sops/encode-unseen-knowledge.md",
-    ]:
-        assert_exists(repo, relative_path)
-    assert_contains(repo, "AGENTS.md", "docs/exec-plans/active/")
-    assert_contains(repo, "AGENTS.md", "docs/sops/")
-    assert_contains(repo, "AGENTS.md", ".codex/skills/harness-repo-bootstrap/scripts/manage_harness.py check")
-
-
-def test_frontend_analysis(tmp_root):
-    repo = tmp_root / "frontend-repo"
-    repo.mkdir()
-    (repo / "package.json").write_text(
-        json.dumps(
-            {
-                "dependencies": {
-                    "react": "^19.0.0",
-                    "vite": "^6.0.0",
-                }
-            },
-            indent=2,
-        )
-        + "\n"
-    )
-    (repo / "src").mkdir()
-    (repo / "src" / "App.tsx").write_text("export default function App() { return null; }\n")
-
-    analysis = run_manager("analyze", "--repo", str(repo))
-    question_ids = {item["id"] for item in analysis["human_confirmations"]}
-    if not analysis["has_frontend"]:
-        raise AssertionError("Frontend repo should be detected")
-    if "frontend_stack_notes" not in question_ids:
-        raise AssertionError("Frontend repo should ask frontend confirmation questions")
-    if "React" not in analysis["frameworks"]:
-        raise AssertionError("React should be detected")
-
-
-def test_closed_loop_plan(tmp_root):
-    repo = tmp_root / "loop-repo"
-    repo.mkdir()
-    (repo / "snake.sh").write_text("#!/usr/bin/env bash\nprintf 'snake\\n'\n")
-    (repo / ".codex" / "skills" / "demo" / "scripts").mkdir(parents=True)
-    (repo / ".codex" / "skills" / "demo" / "scripts" / "tool.py").write_text("print('ignore me')\n")
-    answers = tmp_root / "loop-answers.json"
-    write_answers(answers, project_name="loop-demo")
-    analysis = run_manager("analyze", "--repo", str(repo))
-    if "Shell" not in analysis["languages"]:
-        raise AssertionError("Shell should be detected from target project files")
-    if "Python" in analysis["languages"]:
-        raise AssertionError(".codex skill files should not affect target project language detection")
-    run_manager("init", "--repo", str(repo), "--answers", str(answers))
-
-    plan_result = run_manager(
-        "plan-start",
-        "--repo",
-        str(repo),
-        "--slug",
-        "knowledge-loop",
-        "--goal",
-        "Validate durable knowledge closure",
-    )
-    plan_path = Path(plan_result["plan"])
-    relative_plan = str(plan_path.resolve().relative_to(repo.resolve()))
-    fact = "Install mode must distinguish local and global skill destinations"
-    run_manager(
-        "knowledge-log",
-        "--repo",
-        str(repo),
-        "--plan",
-        relative_plan,
-        "--fact",
-        fact,
-        "--destination",
-        "docs/PRODUCT_SENSE.md",
-    )
-    run_manager(
-        "plan-close",
-        "--repo",
-        str(repo),
-        "--plan",
-        relative_plan,
-        "--summary",
-        "done",
-        expect_success=False,
-    )
-    run_manager(
-        "knowledge-mark-written",
-        "--repo",
-        str(repo),
-        "--plan",
-        relative_plan,
-        "--fact",
-        fact,
-        "--destination",
-        "docs/PRODUCT_SENSE.md",
-        expect_success=False,
-    )
-    run_manager(
-        "knowledge-mark-written",
-        "--repo",
-        str(repo),
-        "--plan",
-        relative_plan,
-        "--fact",
-        fact,
-        "--destination",
-        "docs/PRODUCT_SENSE.md",
-        "--append",
-    )
-    assert_contains(repo, "docs/PRODUCT_SENSE.md", fact)
-    close_result = run_manager(
-        "plan-close",
-        "--repo",
-        str(repo),
-        "--plan",
-        relative_plan,
-        "--summary",
-        "Closed after writing durable knowledge.",
-    )
-    if close_result["status"] != "closed":
-        raise AssertionError("Plan should close after knowledge is marked written")
-    if plan_path.exists():
-        raise AssertionError("Active plan should be moved after close")
-    assert_exists(repo, "docs/exec-plans/completed/" + plan_path.name)
-    check_result = run_manager("check", "--repo", str(repo))
-    if check_result["status"] != "pass":
-        raise AssertionError("Harness check should pass after plan closure")
-
-    formatted_plan = create_formatted_plan(repo)
-    formatted_relative_plan = str(formatted_plan.resolve().relative_to(repo.resolve()))
-    formatted_fact = "snake.sh is the single runtime entrypoint and owns terminal control directly with stty and tput"
-    with (repo / "ARCHITECTURE.md").open("a") as handle:
-        handle.write("\n`snake.sh` is the single runtime entrypoint and owns terminal control directly with `stty` and `tput`.\n")
-    run_manager(
-        "knowledge-mark-written",
-        "--repo",
-        str(repo),
-        "--plan",
-        formatted_relative_plan,
-        "--fact",
-        formatted_fact,
-        "--destination",
-        "ARCHITECTURE.md",
-    )
-
-    id_plan_result = run_manager(
-        "plan-start",
-        "--repo",
-        str(repo),
-        "--slug",
-        "id-knowledge-loop",
-        "--goal",
-        "Validate id-based durable knowledge closure",
-    )
-    id_plan_path = Path(id_plan_result["plan"])
-    id_relative_plan = str(id_plan_path.resolve().relative_to(repo.resolve()))
-    id_fact = "Runtime input is owned by the terminal runner and core game logic remains independent of terminal packages"
-    log_result = run_manager(
-        "knowledge-log",
-        "--repo",
-        str(repo),
-        "--plan",
-        id_relative_plan,
-        "--fact",
-        id_fact,
-        "--destination",
-        "ARCHITECTURE.md",
-    )
-    with (repo / "ARCHITECTURE.md").open("a") as handle:
-        handle.write(
-            "\nThe `main` package owns keyboard input and rendering, while `game` contains pure state transitions.\n"
-        )
-    run_manager(
-        "knowledge-mark-written",
-        "--repo",
-        str(repo),
-        "--plan",
-        id_relative_plan,
-        "--id",
-        log_result["id"],
-        "--evidence",
-        "main package owns keyboard input and rendering",
-    )
-    plan_text = id_plan_path.read_text()
-    if id_fact in (repo / "ARCHITECTURE.md").read_text():
-        raise AssertionError("Id/evidence closure should not require appending the exact fact to the destination")
-    if "| evidence: main package owns keyboard input and rendering" not in plan_text:
-        raise AssertionError("Closed knowledge item should record the verification evidence")
-    run_manager(
-        "plan-close",
-        "--repo",
-        str(repo),
-        "--plan",
-        id_relative_plan,
-        "--summary",
-        "Closed with id-based evidence.",
-    )
-
-
-def create_formatted_plan(repo):
-    plan_path = repo / "docs" / "exec-plans" / "active" / "formatted-plan.md"
-    plan_path.write_text(
-        """# Execution Plan: Formatted Plan
-
-## Durable Knowledge To Capture
-
-- [ ] `snake.sh` is the single runtime entrypoint and owns terminal control directly with `stty` and `tput`. -> `ARCHITECTURE.md`
-"""
-    )
-    return plan_path
-
-
-def test_preserve_unmanaged_docs(tmp_root):
-    repo = tmp_root / "partial-repo"
-    repo.mkdir()
-    (repo / "AGENTS.md").write_text("# Existing user router\n\nKeep this custom content.\n")
-    answers = tmp_root / "partial-answers.json"
-    write_answers(answers)
-
-    result = run_manager("init", "--repo", str(repo), "--answers", str(answers))
-    if "AGENTS.md" not in result["skipped"]:
-        raise AssertionError("Unmanaged AGENTS.md should be skipped")
-    assert_contains(repo, "AGENTS.md", "Keep this custom content.")
-    assert_exists(repo, "docs/PLANS.md")
-
-
-EVALS = [
-    ("empty-repo-init", test_empty_repo_init),
-    ("frontend-analysis", test_frontend_analysis),
-    ("closed-loop-plan", test_closed_loop_plan),
-    ("preserve-unmanaged-docs", test_preserve_unmanaged_docs),
-]
-
-
-def main():
-    results = []
-    with tempfile.TemporaryDirectory() as tmp:
-        tmp_root = Path(tmp)
-        for eval_id, test_func in EVALS:
-            try:
-                test_func(tmp_root)
-                results.append({"id": eval_id, "status": "pass"})
-            except Exception as error:
-                results.append({"id": eval_id, "status": "fail", "error": str(error)})
-
-    passed = sum(1 for result in results if result["status"] == "pass")
-    total = len(results)
-    report = {
-        "score": round((passed / total) * 100),
-        "passed": passed,
-        "total": total,
-        "results": results,
-    }
-    print(json.dumps(report, indent=2) + "\n")
-    if passed != total:
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

package/skills/harness-repo-bootstrap/references/exec-plans.md

@@ -1,39 +0,0 @@
-# Execution Plans
-
-Execution plans are required for multi-step work, risky changes, or tasks that need coordination across files.
-
-## When To Create One
-
-- more than one implementation step is required
-- validation is non-trivial
-- architecture, product, reliability, or security decisions are involved
-- work will span enough time that another agent may resume it later
-
-## Location
-
-- Active: `docs/exec-plans/active/`
-- Completed: `docs/exec-plans/completed/`
-
-## Minimum Sections
-
-- goal
-- scope
-- constraints
-- steps
-- validation
-- durable knowledge to capture
-- completion notes
-
-## Operating Rule
-
-Update the active plan during the work. When the work is done, move it to `completed` and leave behind any durable facts in the right permanent docs.
-
-## Closed Loop
-
-Use the script, not ad hoc manual edits, for the lifecycle:
-
-- `plan-start`: create a new active execution plan
-- `knowledge-log`: append a durable fact that still needs to be written into permanent docs and return its stable id
-- `knowledge-mark-written`: verify and mark a logged fact as written into its permanent doc; prefer `--id <knowledge-id> --evidence "<doc text>"`, and use `--append` only to append the exact fact first
-- `plan-close`: refuse to close cleanly until the listed knowledge items are marked as written to durable docs
-- `check`: run a local handoff check without requiring target-repo CI

package/skills/harness-repo-bootstrap/references/template-policy.md

@@ -1,12 +0,0 @@
-# Template Policy
-
-Every generated file starts with a managed marker:
-
-`<!-- harness-repo-bootstrap:managed -->`
-
-Update behavior:
-
-- `init`: create missing files and skip existing files unless `--force`
-- `update`: create missing files, skip existing unmanaged files, and refresh managed files only when `--refresh-managed` or `--force` is passed
-
-If a file exists without the managed marker, treat it as user-owned unless the human explicitly asks to replace it.

package/skills/harness-repo-bootstrap/references/workflow.md

@@ -1,47 +0,0 @@
-# Workflow
-
-Use this skill in two passes.
-
-## Pass 1: Analyze and Confirm
-
-Run `analyze` before editing repository docs.
-
-Ask the human only about facts that cannot be derived safely from the repo, especially:
-
-- product domain and top-level outcomes
-- intended users or operators
-- production reliability expectations
-- security or compliance constraints
-- frontend experience bar
-- canonical external references worth pinning inside `docs/references/`
-
-Do not ask for facts that can be inferred from source layout, dependency manifests, or existing docs.
-
-Also inspect the analysis for:
-
-- missing durable knowledge that should be written during the task
-- missing execution-plan state
-- which SOPs should be referenced in the generated router docs
-
-## Pass 2: Scaffold or Refresh
-
-Run `sample-answers`, fill the answers, then run `init` or `update`.
-
-Use `init` for first-time adoption.
-Use `update` to add missing managed files or refresh managed files when `--refresh-managed` is passed.
-
-After the script runs, read the generated docs once and tighten weak generic phrases before handing off.
-
-## Ongoing Use
-
-After the scaffold exists:
-
-- create an execution plan before multi-step work
-- use `plan-start` instead of creating plan files manually when possible
-- log durable facts during execution instead of waiting until the end
-- follow the matching SOP for architecture, UI, observability, or knowledge capture work
-- encode durable knowledge back into the repository before closing the task
-- mark logged knowledge items as written after updating the permanent docs
-- use `plan-close` to verify no durable knowledge is left stranded in the active plan
-- run `.codex/skills/harness-repo-bootstrap/scripts/manage_harness.py check --repo <target-repo>` before handoff
-- do not add CI to the target repository unless the human explicitly asks for it