docs: add harness engineering guides and reorganize docs structure

[carlos-alm]

Summary

• Reorganize docs: Separate user-facing guides (docs/guides/) from developer-facing docs (docs/contributing/). Move adding-a-language.md to docs/contributing/ and update all references.
• Add harness engineering use case (docs/use-cases/harness-engineering.md): User-facing guide explaining how codegraph powers harness engineering — the discipline of building systems that prevent AI agents from repeating mistakes. Follows the titan-paradigm.md style with problem statement, codegraph command mappings, roadmap features, and new backlog items.
• Add internal harness engineering reference (docs/contributing/harness-engineering.md): Developer-facing guide with the 9 core practices (AGENTS.md as ToC, remediation-focused linters, silent success/loud failure, mechanical architecture, sub-agents, progress files, e2e verification, wrapper CLIs, continuous GC).

Test plan

• Verify all links in README, SUPPORT, CONTRIBUTING point to new docs/contributing/adding-a-language.md path
• Verify cross-references in new docs resolve correctly
• Review use-case doc for consistency with titan-paradigm.md style

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review: Harness Engineering Documentation

I've conducted a comprehensive review following the 5-phase process:

Todo List

• Phase 1: Root cause analysis - understand problem being solved
• Phase 2: Configuration change detection - check for high-risk changes
• Phase 3: Test integrity - look for red flags
• Phase 4: Code quality - review documentation changes
• Phase 5: Backlog compliance - rate against criteria
• Final Assessment: Provide rating and recommendation

---

Root Cause Analysis

Problem Being Solved: Adding comprehensive harness engineering documentation to codegraph. The PR addresses the gap where users need guidance on how to systematically prevent AI agent mistakes using codegraph as enforcement infrastructure.

Why This Approach: Creates both user-facing (use-cases/) and developer-facing (contributing/) documentation, following established patterns in the codebase. The reorganization separates concerns properly - user guides vs contributor docs.

Risk Assessment: Zero risk - this is documentation-only with no code changes.

---

Phase 2: Configuration Changes ✅

No high-risk configuration changes detected. Only documentation files were modified:

• File moves and reference updates
• New documentation added
• No linting, build, or test configuration modified

---

Phase 3: Test Integrity ✅

No test files modified. No test expectations changed. No red flags detected.

---

Phase 4: Code Quality Assessment

Strengths:

1. Excellent content quality: Both documents are comprehensive, well-structured, and directly applicable
2. Proper file organization: Clean separation of user-facing (docs/use-cases/) vs developer-facing (docs/contributing/) documentation
3. Reference integrity: All links to moved adding-a-language.md file correctly updated in README, CONTRIBUTING, and SUPPORT
4. Consistent style: Matches existing documentation patterns (like titan-paradigm.md)
5. Actionable content: Provides concrete commands, examples, and implementation steps rather than abstract concepts

Technical accuracy:

• Command examples are correct (codegraph check --staged --no-new-cycles -T)
• Configuration examples match actual .codegraphrc.json schema
• References to existing features are accurate

Areas for improvement (minor):

• Could benefit from a cross-reference between the two docs (user guide → contributing guide)
• Some backlog items in use-cases doc might be more appropriate in actual BACKLOG.md

---

Backlog Compliance

• Zero-dep: ✅ — No new dependencies added, pure documentation
• Foundation-aligned: ✅ — Aligns with all principles, promotes zero-infrastructure approach
• Problem-fit: 5/5 — Directly addresses the core problem of "AI agents waste tokens, hallucinate dependencies, miss blast radius" by providing systematic prevention
• Breaking: No — Purely additive documentation, no API changes
• Tier: Tier 1 (zero-dep ✅ + foundation-aligned ✅)

---

Critical Concerns

None. This is high-quality documentation that fills an important gap.

---

Final Assessment

## Root Cause Analysis
**Problem Being Solved**: Adding systematic harness engineering guidance to prevent AI agent mistakes using codegraph infrastructure
**Why This Approach**: Clean separation of user vs developer docs, follows established patterns, comprehensive coverage
**Risk Assessment**: Zero risk - documentation only

## Backlog Compliance
- Zero-dep: ✅ — No new dependencies
- Foundation-aligned: ✅ — Promotes zero-infrastructure approach
- Problem-fit: 5/5 — Directly addresses core AI agent navigation problems
- Breaking: No — Purely additive documentation
- Tier: 1

## Critical Concerns
None

## Final Recommendation
- Rating: ⭐⭐⭐⭐⭐ (5/5)
- Action: APPROVE
- Reasoning: Exceptional documentation that directly addresses user needs with actionable, technically accurate content. Zero risk, high value.

Recommendation: APPROVE - This is exemplary documentation that provides immediate value to users wanting to implement harness engineering patterns with codegraph.

[greptile-apps]

Greptile Summary

This PR reorganizes the docs directory by separating user-facing (docs/guides/) from developer-facing (docs/contributing/) content, moves adding-a-language.md to the new docs/contributing/ directory, and adds two new harness engineering documents — one user-facing use-case guide and one internal developer reference. All three reference sites (README, CONTRIBUTING, SUPPORT) have been correctly updated for the renamed file path, and all cross-reference links in the new docs resolve to existing files.

Notable items:

• "One PR = one concern" (CLAUDE.md): The PR bundles two independent changes — the adding-a-language.md rename/restructure and the two new harness engineering docs. Per the project's own guidelines, these could reasonably be separate PRs (e.g. docs: restructure guides vs contributing + docs: add harness engineering guides). Given both are documentation-only with no code impact, this is low-risk, but worth flagging for future PRs.
• All relative links in both new docs were verified: titan-paradigm.md, recommended-practices.md, ai-agent-guide.md, both roadmap files, and the Claude Code hooks README all exist at the expected paths.
• The docs/contributing/harness-engineering.md internal guide is thorough (9 practices, code examples, mapping table) and consistent with the project's existing codegraph-centric style. The use-case doc follows the titan-paradigm.md structure as intended.

Confidence Score: 5/5

• This PR is safe to merge — it is documentation-only with no code changes, and all updated links resolve correctly.
• All link updates are correct and verified against the actual file tree. The two new docs contain no executable code and all their cross-references resolve. The only process note is that CLAUDE.md's "one PR = one concern" guideline is mildly stretched, but the risk is purely organizational and carries zero runtime impact.
• No files require special attention.

Important Files Changed

Filename	Overview
CONTRIBUTING.md	Single link update from docs/guides/adding-a-language.md to docs/contributing/adding-a-language.md — correctly reflects the renamed file path.
README.md	Single link update to match the renamed adding-a-language.md path — correct and consistent with the other reference updates.
SUPPORT.md	Single link update for the moved adding-a-language.md file; the docs/guides/recommended-practices.md link (unchanged) still resolves correctly.
docs/contributing/adding-a-language.md	Pure rename from docs/guides/ to docs/contributing/ — no content changes, all three reference sites (README, CONTRIBUTING, SUPPORT) have been updated.
docs/contributing/harness-engineering.md	New developer-facing internal guide covering 9 harness engineering practices. Cross-reference to ../examples/claude-code-hooks/README.md resolves correctly. Content is well-structured and internally consistent.
docs/use-cases/harness-engineering.md	New user-facing use-case doc. All relative links verified: ../roadmap/ROADMAP.md, ../roadmap/BACKLOG.md, ../examples/claude-code-hooks/README.md, ../guides/recommended-practices.md, ../guides/ai-agent-guide.md, and ./titan-paradigm.md all resolve to existing files.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Before
        A1[docs/guides/adding-a-language.md]
    end

    subgraph After["After (this PR)"]
        B1[docs/contributing/adding-a-language.md]
        B2[docs/contributing/harness-engineering.md\nNEW — internal dev reference]
        B3[docs/use-cases/harness-engineering.md\nNEW — user-facing guide]
        B4[docs/guides/recommended-practices.md\nunchanged]
    end

    subgraph References
        R1[README.md]
        R2[CONTRIBUTING.md]
        R3[SUPPORT.md]
    end

    A1 -- renamed --> B1
    R1 -- link updated --> B1
    R2 -- link updated --> B1
    R3 -- link updated --> B1

    B3 -- cross-references --> B4
    B3 -- cross-references --> B2
    B3 --> C1[docs/roadmap/ROADMAP.md]
    B3 --> C2[docs/roadmap/BACKLOG.md]
    B3 --> C3[docs/examples/claude-code-hooks/README.md]
    B2 --> C3

Loading

_{Reviews (1): Last reviewed commit: "docs: add harness engineering guides and..." | Re-trigger Greptile}

[carlos-alm]

Addressed Claude's review feedback:

• Cross-references between docs: Added a link from the user-facing guide (docs/use-cases/harness-engineering.md) to the contributing guide in the Further Reading section, and added a Further Reading section in the contributing guide (docs/contributing/harness-engineering.md) linking back to the use-case guide.

• Backlog items placement: The backlog items in the use-cases doc are intentionally placed there as part of the "What's on the Roadmap" narrative — they show users what harness-related features are coming. They reference the actual ROADMAP.md and BACKLOG.md files via links, so users can find the canonical tracking locations. Moving them would break the narrative flow of the use-case document.

Commit: afafbb4

[carlos-alm]

@greptileai

[carlos-alm]

@claude