I need to explore the template and resource files in /root/projects/learn-harness-engineering that relate to harness engineering templates and best practices.

Please do a VERY THOROUGH exploration:

1. Look at docs/resources/en/ and docs/resources/zh/ for any template files, especially:
   - CLAUDE.md templates
   - AGENTS.md templates
   - Any harness setup guides
   - Any reference documents about harness engineering
2. Look at the actual harness files in project directories:
   - projects/project-01/ through project-06/ - look at starter/ directories for CLAUDE.md, AGENTS.md, feature_list.json, init.sh, etc.
   - Read at least 2-3 of these completely to understand the pattern
3. Look at projects/shared/ for the base harness setup

I specifically want to see:
- Complete examples of CLAUDE.md files used in projects
- Complete examples of AGENTS.md files
- feature_list.json format and content
- init.sh scripts
- Any other harness artifacts

Report back with FULL file contents of the most representative examples.


I'll conduct a thorough exploration of the template and resource files in the harness engineering project. Let me start by mapping out the directory structure and then diving into the specific files you mentioned.


Bash

find /root/projects/learn-harness-engineering -type f -name "*.md" | head -20


Let me explore the directory structure more systematically:


total 224
drwxr-xr-x  6 root root     178 Apr  1 11:55 .
drwxr-xr-x 11  501 games    186 Apr  1 11:58 ..
-rw-r--r--  1 root root    3093 Apr  1 11:55 CLAUDE.md
drwxr-xr-x  5 root root      60 Apr  1 11:55 docs
drwxr-xr-x  8 root root     163 Apr  1 11:55 .git
drwxr-xr-x  3 root root      23 Apr  1 11:55 .github
-rw-r--r--  1 root root     324 Apr  1 11:55 .gitignore
-rw-r--r--  1 root root     512 Apr  1 11:55 package.json
-rw-r--r--  1 root root  159408 Apr  1 11:55 package-lock.json
drwxr-xr-x  9 root root     128 Apr  1 11:55 projects
-rw-r--r--  1 root root   27241 Apr  1 11:55 README-CN.md
-rw-r--r--  1 root root   27813 Apr  1 11:55 README.md


total 0
drwxr-xr-x 9 root root 128 Apr  1 11:55 .
drwxr-xr-x 6 root root 178 Apr  1 11:55 ..
drwxr-xr-x 4 root root  54 Apr  1 11:55 project-01
drwxr-xr-x 4 root root  54 Apr  1 11:55 project-02
drwxr-xr-x 4 root root  54 Apr  1 11:55 project-03
drwxr-xr-x 4 root root  54 Apr  1 11:55 project-04
drwxr-xr-x 4 root root  54 Apr  1 11:55 project-05
drwxr-xr-x 4 root root  54 Apr  1 11:55 project-06
drwxr-xr-x 5 root root 133 Apr  1 11:55 shared


total 4
drwxr-xr-x 5 root root  60 Apr  1 11:55 .
drwxr-xr-x 6 root root 178 Apr  1 11:55 ..
drwxr-xr-x 5 root root  71 Apr  1 11:55 en
-rw-r--r-- 1 root root 601 Apr  1 11:55 index.md
drwxr-xr-x 3 root root  37 Apr  1 11:55 .vitepress
drwxr-xr-x 5 root root  71 Apr  1 11:55 zh


find /root/projects/learn-harness-engineering/docs/resources -type f 2>/dev/null | head -20


(Bash completed with no output)


find /root/projects/learn-harness-engineering/docs -type d


Great! Now let me explore the templates and resources directories:


find /root/projects/learn-harness-engineering/docs/en/resources -type f


Perfect! Now let me explore the project directories and read the templates:


total 8
drwxr-xr-x 4 root root   54 Apr  1 11:55 .
drwxr-xr-x 9 root root  128 Apr  1 11:55 ..
-rw-r--r-- 1 root root 1515 Apr  1 11:55 README.md
drwxr-xr-x 6 root root 4096 Apr  1 11:55 solution
drwxr-xr-x 5 root root  155 Apr  1 11:55 starter


find /root/projects/learn-harness-engineering/projects/project-0{1,2,3,4,5,6}/starter -type f


Excellent! Now let me read the key template files and project files:


1	# CLAUDE.md
2
3	This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5	## Project Overview
6
7	Learn Harness Engineering is a project-based course on building reliable coding environments for AI agents. The repo contains a VitePress documentation site plus hands-on project code.
8
9	## Commands
10
11	```sh
12	# Documentation site
13	npm install
14	npm run docs:dev        # Dev server with hot reload (VitePress)
15	npm run docs:build      # Production build
16	npm run docs:preview    # Preview built site
17
18	# Run lecture code examples
19	npx tsx docs/lectures/<lecture-dir>/code/<file>.ts
20
21	# Project Electron apps (from each project directory)
22	cd projects/project-NN/starter  # or solution/
23	npm install
24	npm run dev              # Build + launch Electron (via scripts/dev.js)
25	npm run check            # Type-check both tsconfig.json and tsconfig.node.json
26	npm run test             # Vitest run (single run)
27	npm run test:watch       # Vitest watch mode
28	```
29
30	## Repository Structure
31
32	- `docs/` — VitePress documentation site (lectures, projects, resources)
33	- `docs/.vitepress/config.mts` — Nav/sidebar config for both EN and ZH locales
34	- `docs/lectures/` — 12 lectures, each with `index.md` + `code/` examples
35	- `docs/projects/` — 6 project descriptions
36	- `docs/resources/` — Bilingual (en/zh) templates, references, OpenAI advanced pack
37	- `projects/shared/` — Shared Electron + TypeScript + React foundation
38	- `projects/project-NN/` — Per-project `starter/` and `solution/` directories
39
40	## Architecture
41
42	The course revolves around an Electron knowledge-base desktop app that evolves across 6 projects:
43	- **Main process** (`src/main/`): Window management, IPC handlers, service initialization
44	- **Preload** (`src/preload/`): contextBridge exposing typed API to renderer
45	- **Renderer** (`src/renderer/`): React UI with document list, Q&A panel, status bar
46	- **Services** (`src/services/`): DocumentService, IndexingService, QaService, PersistenceService
47	- **Shared types** (`src/shared/types.ts`): Cross-boundary interfaces and IPC channel constants
48
49	Each project's starter/solution is a complete copy of the Electron app at that evolutionary stage. P(N+1) starter is derived from P(N) solution. The shared foundation is in `projects/shared/`.
50
51	## Key Patterns
52
53	- IPC channels defined as constants in `src/shared/types.ts` (IPC_CHANNELS) — single source of truth
54	- All data stored locally as JSON/text files (no database)
55	- Mock Q&A returns structured answers with citations (no real LLM API)
56	- Harness files in project roots: AGENTS.md, CLAUDE.md, feature_list.json, init.sh, claude-progress.md
57	- Progressive disclosure: short AGENTS.md entrypoint linking to focused docs
58	- Each project has two tsconfigs: `tsconfig.json` (renderer) and `tsconfig.node.json` (main/preload)
59
60	## Bilingual Content
61
62	All content exists in both English and Chinese. Documentation lives in shared `docs/lectures/` and `docs/projects/` dirs (content is bilingual within each file). Resources have separate `docs/resources/en/` and `docs/resources/zh/` directories. Keep both in sync.
63


1	# CLAUDE.md
2
3	You are working in a repository designed for long-running implementation work.
4	Prioritize reliable completion, continuity across sessions, and explicit
5	verification over speed.
6
7	## Operating Loop
8
9	At the start of every session:
10
11	1. Run `pwd` and confirm you are in the expected repository root.
12	2. Read `claude-progress.md`.
13	3. Read `feature_list.json`.
14	4. Review recent commits with `git log --oneline -5`.
15	5. Run `./init.sh`.
16	6. Check whether the baseline smoke or end-to-end path is already broken.
17
18	Then select exactly one unfinished feature and work only on that feature until
19	you either verify it or document why it is blocked.
20
21	## Rules
22
23	- One active feature at a time.
24	- Do not claim completion without runnable evidence.
25	- Do not rewrite the feature list to hide unfinished work.
26	- Do not remove or weaken tests just to make the task look complete.
27	- Use repository artifacts as the system of record.
28
29	## Required Files
30
31	- `feature_list.json`
32	- `claude-progress.md`
33	- `init.sh`
34	- `session-handoff.md` when a compact handoff is useful
35
36	## Completion Gate
37
38	A feature can move to `passing` only after the required verification succeeds
39	and the result is recorded.
40
41	## Before You Stop
42
43	1. Update the progress log.
44	2. Update the feature state.
45	3. Record what is still broken or unverified.
46	4. Commit once the repository is safe to resume.
47	5. Leave a clean restart path for the next session.
48


1	# AGENTS.md
2
3	This repository is designed for long-running coding-agent work. The goal is not
4	to maximize raw code output. The goal is to leave the repo in a state where the
5	next session can continue without guessing.
6
7	## Startup Workflow
8
9	Before writing code:
10
11	1. Confirm the working directory with `pwd`.
12	2. Read `claude-progress.md` for the latest verified state and next step.
13	3. Read `feature_list.json` and choose the highest-priority unfinished feature.
14	4. Review recent commits with `git log --oneline -5`.
15	5. Run `./init.sh`.
16	6. Run the required smoke or end-to-end verification before starting new work.
17
18	If baseline verification is already failing, fix that first. Do not stack new
19	feature work on top of a broken starting state.
20
21	## Working Rules
22
23	- Work on one feature at a time.
24	- Do not mark a feature complete just because code was added.
25	- Keep changes within the selected feature scope unless a blocker forces a
26	  narrow supporting fix.
27	- Do not silently change verification rules during implementation.
28	- Prefer durable repo artifacts over chat summaries.
29
30	## Required Artifacts
31
32	- `feature_list.json`: source of truth for feature state
33	- `claude-progress.md`: session log and current verified status
34	- `init.sh`: standard startup and verification path
35	- `session-handoff.md`: optional compact handoff for larger sessions
36
37	## Definition Of Done
38
39	A feature is done only when all of the following are true:
40
41	- the target behavior is implemented
42	- the required verification actually ran
43	- evidence is recorded in `feature_list.json` or `claude-progress.md`
44	- the repository remains restartable from the standard startup path
45
46	## End Of Session
47
48	Before ending a session:
49
50	1. Update `claude-progress.md`.
51	2. Update `feature_list.json`.
52	3. Record any unresolved risk or blocker.
53	4. Commit with a descriptive message once the work is in a safe state.
54	5. Leave the repo clean enough for the next session to run `./init.sh`
55	   immediately.
56


1	{
2	  "project": "replace-with-project-name",
3	  "last_updated": "YYYY-MM-DD",
4	  "rules": {
5	    "single_active_feature": true,
6	    "passing_requires_evidence": true,
7	    "do_not_skip_verification": true
8	  },
9	  "status_legend": {
10	    "not_started": "Work has not begun.",
11	    "in_progress": "The feature is the current active task.",
12	    "blocked": "Work cannot continue until a documented blocker is resolved.",
13	    "passing": "Required verification has passed and evidence is recorded."
14	  },
15	  "features": [
16	    {
17	      "id": "chat-001",
18	      "priority": 1,
19	      "area": "chat",
20	      "title": "Create a new conversation",
21	      "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",
22	      "status": "not_started",
23	      "verification": [
24	        "Open the app.",
25	        "Click New Chat.",
26	        "Verify a new conversation appears in the sidebar.",
27	        "Verify the main panel shows an empty conversation state."
28	      ],
29	      "evidence": [],
30	      "notes": ""
31	    },
32	    {
33	      "id": "chat-002",
34	      "priority": 2,
35	      "area": "chat",
36	      "title": "Send a message in the current conversation",
37	      "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",
38	      "status": "not_started",
39	      "verification": [
40	        "Open an existing conversation.",
41	        "Type a message into the input.",
42	        "Submit the message.",
43	        "Verify the new message appears in the thread."
44	      ],
45	      "evidence": [],
46	      "notes": ""
47	    },
48	    {
49	      "id": "chat-003",
50	      "priority": 3,
51	      "area": "chat",
52	      "title": "Persist the active conversation list",
53	      "user_visible_behavior": "A user sees previously created conversations after restarting the app.",
54	      "status": "not_started",
55	      "verification": [
56	        "Create two conversations.",
57	        "Restart the app.",
58	        "Verify both conversations still appear in the sidebar."
59	      ],
60	      "evidence": [],
61	      "notes": ""
62	    }
63	  ]
64	}
65


1	#!/usr/bin/env bash
2
3	set -euo pipefail
4
5	ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
6	cd "$ROOT_DIR"
7
8	# Replace these commands with the correct commands for your repository.
9	INSTALL_CMD=(npm install)
10	VERIFY_CMD=(npm test)
11	START_CMD=(npm run dev)
12
13	echo "==> Working directory: $PWD"
14	echo "==> Syncing dependencies"
15	"${INSTALL_CMD[@]}"
16
17	echo "==> Running baseline verification"
18	"${VERIFY_CMD[@]}"
19
20	echo "==> Startup command"
21	printf '    %q' "${START_CMD[@]}"
22	printf '\n'
23
24	if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
25	  echo "==> Starting the app"
26	  exec "${START_CMD[@]}"
27	fi
28
29	echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."
30


Now let me read the project-specific files:


1	# AGENTS.md -- Project 02: Agent-Readable Workspace
2
3	## Quick Start
4
5	1. Run `npm install && npm run check` to verify the build.
6	2. Read `docs/ARCHITECTURE.md` for layer structure.
7	3. Check `feature_list.json` for what needs to be done.
8
9	## Layers
10
11	- Main process: `src/main/` -- window, IPC, services
12	- Preload: `src/preload/` -- bridge API
13	- Renderer: `src/renderer/` -- React UI
14	- Services: `src/services/` -- business logic
15
16	## Conventions
17
18	- TypeScript strict mode. No `any` without comment.
19	- Named exports only.
20	- IPC channels in `src/shared/types.ts`.
21


1	{
2	  "project": "project-02",
3	  "description": "Agent-readable workspace with import, detail view, and persistence",
4	  "features": [
5	    {
6	      "id": "window-launch",
7	      "name": "Window Launch",
8	      "description": "Electron app opens a BrowserWindow with correct dimensions and preload script",
9	      "status": "pass",
10	      "evidence": "Carried over from P1 -- verified working",
11	      "testedAt": "2026-03-30T10:00:00Z"
12	    },
13	    {
14	      "id": "document-list",
15	      "name": "Document List Panel",
16	      "description": "Left sidebar shows imported documents with empty state message",
17	      "status": "pass",
18	      "evidence": "Carried over from P1 -- verified working",
19	      "testedAt": "2026-03-30T10:05:00Z"
20	    },
21	    {
22	      "id": "question-panel",
23	      "name": "Question Panel",
24	      "description": "Bottom input bar accepts questions and submits via IPC",
25	      "status": "pass",
26	      "evidence": "Carried over from P1 -- verified working",
27	      "testedAt": "2026-03-30T10:08:00Z"
28	    },
29	    {
30	      "id": "data-directory",
31	      "name": "Data Directory",
32	      "description": "PersistenceService creates and manages userData/knowledge-base-data directory",
33	      "status": "pass",
34	      "evidence": "Carried over from P1 -- verified working",
35	      "testedAt": "2026-03-30T10:10:00Z"
36	    },
37	    {
38	      "id": "document-import",
39	      "name": "Document Import",
40	      "description": "Users can import .txt and .md files via ImportPanel with file picker",
41	      "status": "not-started",
42	      "evidence": null,
43	      "testedAt": null
44	    },
45	    {
46	      "id": "document-detail",
47	      "name": "Document Detail with Content",
48	      "description": "DocumentDetail shows full document content, metadata, and delete button",
49	      "status": "not-started",
50	      "evidence": null,
51	      "testedAt": null
52	    },
53	    {
54	      "id": "basic-persistence",
55	      "name": "Basic Persistence",
56	      "description": "Imported documents persist across app restarts via filesystem storage",
57	      "status": "not-started",
58	      "evidence": null,
59	      "testedAt": null
60	    }
61	  ]
62	}
63


1	# AGENTS.md -- Project 03: Scope Control and Grounded Verification
2
3	## Quick Start
4
5	1. Run `npm install && npm run check` to verify the build.
6	2. Read `docs/ARCHITECTURE.md` for layer structure.
7	3. Read `docs/PRODUCT.md` for feature requirements.
8	4. Check `feature_list.json` for what needs to be done.
9
10	## Layers
11
12	- Main: `src/main/` -- window, IPC, services
13	- Preload: `src/preload/` -- bridge API
14	- Renderer: `src/renderer/` -- React UI
15	- Services: `src/services/` -- business logic
16
17	## Conventions
18
19	- TypeScript strict mode. No `any` without comment.
20	- Named exports only.
21	- IPC channels in `src/shared/types.ts`.
22
23	## Features to Implement
24
25	The new features for this project are:
26
27	1. **Document Chunking** -- IndexingService splits documents into ~500 char chunks
28	2. **Metadata Extraction** -- Extract word count, line count, file type on import
29	3. **Indexing Status UI** -- StatusBar shows indexing progress with counts
30	4. **Grounded Q&A** -- QaService returns answers with citations and confidence
31
32	Check `feature_list.json` for current status.
33
34	## Definition of Done
35
36	A feature is "done" when:
37
38	1. TypeScript compiles without errors (`npm run check`).
39	2. The app launches and the feature works.
40	3. The feature appears in `feature_list.json` with status `"pass"` and evidence.
41
42	## Session Handoff
43
44	When resuming work, read `session-handoff.md` for context from the previous session.
45


1	{
2	  "project": "project-03",
3	  "description": "Scope control and grounded verification with indexing, metadata, and grounded QA",
4	  "features": [
5	    {
6	      "id": "window-launch",
7	      "name": "Window Launch",
8	      "description": "Electron app opens a BrowserWindow with correct dimensions and preload script",
9	      "status": "pass",
10	      "evidence": "Carried over from P2 -- verified working",
11	      "testedAt": "2026-03-30T10:00:00Z"
12	    },
13	    {
14	      "id": "document-list",
15	      "name": "Document List Panel",
16	      "description": "Left sidebar shows imported documents with empty state message",
17	      "status": "pass",
18	      "evidence": "Carried over from P2 -- verified working",
19	      "testedAt": "2026-03-30T10:05:00Z"
20	    },
21	    {
22	      "id": "question-panel",
23	      "name": "Question Panel",
24	      "description": "Bottom input bar accepts questions and submits via IPC",
25	      "status": "pass",
26	      "evidence": "Carried over from P2 -- verified working",
27	      "testedAt": "2026-03-30T10:08:00Z"
28	    },
29	    {
30	      "id": "data-directory",
31	      "name": "Data Directory",
32	      "description": "PersistenceService creates and manages userData/knowledge-base-data directory",
33	      "status": "pass",
34	      "evidence": "Carried over from P2 -- verified working",
35	      "testedAt": "2026-03-30T10:10:00Z"
36	    },
37	    {
38	      "id": "document-import",
39	      "name": "Document Import",
40	      "description": "Users can import .txt and .md files via ImportPanel with file picker",
41	      "status": "pass",
42	      "evidence": "Carried over from P2 -- verified working",
43	      "testedAt": "2026-03-30T11:00:00Z"
44	    },
45	    {
46	      "id": "document-detail",
47	      "name": "Document Detail with Content",
48	      "description": "DocumentDetail shows full document content, metadata, and delete button",
49	      "status": "pass",
50	      "evidence": "Carried over from P2 -- verified working",
51	      "testedAt": "2026-03-30T11:15:00Z"
52	    },
53	    {
54	      "id": "basic-persistence",
55	      "name": "Basic Persistence",
56	      "description": "Imported documents persist across app restarts via filesystem storage",
57	      "status": "pass",
58	      "evidence": "Carried over from P2 -- verified working",
59	      "testedAt": "2026-03-30T11:30:00Z"
60	    },
61	    {
62	      "id": "document-chunking",
63	      "name": "Document Chunking",
64	      "description": "IndexingService splits documents into ~500 char chunks at paragraph boundaries",
65	      "status": "not-started",
66	      "evidence": null,
67	      "testedAt": null
68	    },
69	    {
70	      "id": "metadata-extraction",
71	      "name": "Metadata Extraction",
72	      "description": "On import, extract word count, line count, and file type metadata from documents",
73	      "status": "not-started",
74	      "evidence": null,
75	      "testedAt": null
76	    },
77	    {
78	      "id": "indexing-status-ui",
79	      "name": "Indexing Status in StatusBar",
80	      "description": "StatusBar shows indexing progress with document counts and status indicator",
81	      "status": "not-started",
82	      "evidence": null,
83	      "testedAt": null
84	    },
85	    {
86	      "id": "grounded-qa",
87	      "name": "Grounded Q&A with Citations",
88	      "description": "QaService returns answers with document citations and confidence scores",
89	      "status": "not-started",
90	      "evidence": null,
91	      "testedAt": null
92	    }
93	  ]
94	}
95


Now let me check the OpenAI advanced template and read more project examples:


1	# AGENTS.md
2
3	This repository is optimized for long-running coding-agent work. Keep this file
4	short. Use it as the routing layer into the system-of-record docs, not as a
5	giant instruction dump.
6
7	## Startup Workflow
8
9	Before changing code:
10
11	1. Confirm the repo root with `pwd`.
12	2. Read `ARCHITECTURE.md` for the current system map and hard dependency rules.
13	3. Read `docs/QUALITY_SCORE.md` to see which domains or layers are weakest.
14	4. Read `docs/PLANS.md`, then open the active plan you are working from.
15	5. Read the relevant product spec in `docs/product-specs/`.
16	6. Run the standard bootstrap and verification path for this repo.
17	7. If baseline verification is failing, repair the baseline before adding scope.
18
19	## Routing Map
20
21	- `ARCHITECTURE.md`: domain map, layer model, dependency rules
22	- `docs/design-docs/index.md`: design decisions and core beliefs
23	- `docs/product-specs/index.md`: current product behaviors and acceptance targets
24	- `docs/PLANS.md`: plan lifecycle and execution-plan policy
25	- `docs/QUALITY_SCORE.md`: product-domain and layer health
26	- `docs/RELIABILITY.md`: runtime signals, benchmarks, and restart expectations
27	- `docs/SECURITY.md`: secrets, sandbox, data, and external-action rules
28	- `docs/FRONTEND.md`: UI constraints, design system rules, accessibility checks
29
30	## Working Contract
31
32	- Work from one bounded plan or feature slice at a time.
33	- Do not mark work done from code inspection alone; runnable evidence is
34	  required.
35	- If you change behavior, update the matching product, plan, or reliability
36	  docs in the same session.
37	- If you see repeated review feedback, promote it into a mechanical rule, check,
38	  or linter instead of re-explaining it in chat.
39	- Keep generated material in `docs/generated/` and source references in
40	  `docs/references/`.
41	- Prefer adding small, current docs over growing this file.
42
43	## Definition Of Done
44
45	A change is done only when all of the following are true:
46
47	- target behavior is implemented
48	- required verification actually ran
49	- evidence is linked from the relevant plan or quality document
50	- affected docs remain current
51	- the repository can restart cleanly from the standard startup path
52
53	## End Of Session
54
55	Before ending a session:
56
57	1. Update the active execution plan.
58	2. Update `docs/QUALITY_SCORE.md` if any domain or layer meaningfully changed.
59	3. Record new debt in `docs/exec-plans/tech-debt-tracker.md` if you deferred it.
60	4. Move finished plans to `docs/exec-plans/completed/` when appropriate.
61	5. Leave the repo in a restartable state with a clear next action.
62


1	# AGENTS.md
2
3	This repository is designed for long-running coding-agent work. The goal is not
4	to maximize raw code output. The goal is to leave the repo in a state where the
5	next session can continue without guessing.
6
7	## Startup Workflow
8
9	Before writing code:
10
11	1. Confirm the working directory with `pwd`.
12	2. Read `claude-progress.md` for the latest verified state and next step.
13	3. Read `feature_list.json` and choose the highest-priority unfinished feature.
14	4. Review recent commits with `git log --oneline -5`.
15	5. Run `./init.sh`.
16	6. Run the required smoke or end-to-end verification before starting new work.
17
18	If baseline verification is already failing, fix that first. Do not stack new
19	feature work on top of a broken starting state.
20
21	## Working Rules
22
23	- Work on one feature at a time.
24	- Do not mark a feature complete just because code was added.
25	- Keep changes within the selected feature scope unless a blocker forces a
26	  narrow supporting fix.
27	- Do not silently change verification rules during implementation.
28	- Prefer durable repo artifacts over chat summaries.
29
30	## Runtime Observability
31
32	All services use structured logging via `src/services/logger.ts`. Log output is
33	JSON-formatted with timestamp, level, service name, and message. Log levels:
34	DEBUG, INFO, WARN, ERROR.
35
36	When debugging, check logs for:
37	- Service initialization events at startup
38	- IPC channel invocations and their parameters
39	- Indexing chunk counts and content lengths
40	- Q&A confidence scores and citation counts
41
42	## Architecture Constraints
43
44	The following layer boundaries are enforced by `scripts/check-architecture.sh`:
45
46	- **Renderer** must not import `fs`, `path`, or any Node.js core modules.
47	- **Services** must not import Electron IPC or renderer-specific modules.
48	- **Preload** must only expose the typed API via contextBridge.
49
50	Run `bash scripts/check-architecture.sh` before committing.
51
52	## Required Artifacts
53
54	- `feature_list.json`: source of truth for feature state
55	- `claude-progress.md`: session log and current verified status
56	- `init.sh`: standard startup and verification path
57	- `session-handoff.md`: optional compact handoff for larger sessions
58	- `clean-state-checklist.md`: pre-commit repository health check
59
60	## Definition Of Done
61
62	A feature is done only when all of the following are true:
63
64	- the target behavior is implemented
65	- the required verification actually ran
66	- evidence is recorded in `feature_list.json` or `claude-progress.md`
67	- the repository remains restartable from the standard startup path
68	- `scripts/check-architecture.sh` passes with no violations
69
70	## End Of Session
71
72	Before ending a session:
73
74	1. Update `claude-progress.md`.
75	2. Update `feature_list.json`.
76	3. Record any unresolved risk or blocker.
77	4. Run `bash scripts/check-architecture.sh`.
78	5. Commit with a descriptive message once the work is in a safe state.
79	6. Leave the repo clean enough for the next session to run `./init.sh`
80	   immediately.
81


1	# AGENTS.md -- Project 06: Runtime Observability and Debugging (Capstone)
2
3	## Startup Rules
4
5	1. Read this file.
6	2. Run `npm install && npm run check` to verify the build.
7	3. The app should launch with `npm run dev`.
8
9	## Project Description
10
11	This is the capstone project for the Learn Harness Engineering course. It combines all features from previous projects:
12	- Document import, indexing, and Q&A
13	- Conversation history view
14	- Structured logging for observability
15	- Clean state management for testing
16
17	## What to Build
18
19	The application needs:
20	1. A working ConversationHistory component with chat-style display
21	2. Feedback buttons on Q&A responses (thumbs up/down)
22	3. Structured logging that all services use
23	4. A clean state reset function
24	5. Benchmark scripts for measuring performance
25
26	## Conventions
27
28	- TypeScript strict mode.
29	- Named exports only.
30	- IPC channels defined in `src/shared/types.ts`.
31	- Services use constructor-injected `PersistenceService`.
32


1	# Clean State Checklist
2
3	- [ ] The standard startup path still works.
4	- [ ] The standard verification path still runs.
5	- [ ] Current progress is recorded in the progress log.
6	- [ ] Feature state reflects what is actually passing versus unverified.
7	- [ ] No half-finished step is left undocumented.
8	- [ ] The next session can continue without manual repair.
9


Let me read some additional template files and check other important artifacts:


1	# Session Handoff
2
3	## Verified Now
4
5	- What is currently working:
6	- What verification actually ran:
7
8	## Changed This Session
9
10	- Code or behavior added:
11	- Infrastructure or harness changes:
12
13	## Broken Or Unverified
14
15	- Known defect:
16	- Unverified path:
17	- Risk for the next session:
18
19	## Next Best Step
20
21	- Highest-priority unfinished feature:
22	- Why it is next:
23	- What counts as passing:
24	- What must not change during that step:
25
26	## Commands
27
28	- Startup:
29	- Verification:
30	- Focused debug command:
31


1	# Progress Log
2
3	## Current Verified State
4
5	- Repository root:
6	- Standard startup path:
7	- Standard verification path:
8	- Current highest-priority unfinished feature:
9	- Current blocker:
10
11	## Session Log
12
13	### Session 001
14
15	- Date:
16	- Goal:
17	- Completed:
18	- Verification run:
19	- Evidence captured:
20	- Commits:
21	- Files or artifacts updated:
22	- Known risk or unresolved issue:
23	- Next best step:
24
25	### Session 002
26
27	- Date:
28	- Goal:
29	- Completed:
30	- Verification run:
31	- Evidence captured:
32	- Commits:
33	- Files or artifacts updated:
34	- Known risk or unresolved issue:
35	- Next best step:
36


1	# Quality Document
2
3	A quality snapshot for each product domain and architectural layer. Both agents and humans can use this document to quickly understand where the codebase is strong and where it needs work.
4
5	**Update cadence:** After each significant session, or before starting a new phase of work.
6
7	**Grading scale:**
8
9	- **A**: All verification passing, clean architecture, agent-legible, stable tests
10	- **B**: Verification passing, mostly clean, minor gaps in legibility or test coverage
11	- **C**: Partially working, known gaps, some code areas hard for agents to understand
12	- **D**: Not working, or major structural issues
13
14	---
15
16	## Product Domains
17
18	| Domain | Grade | Verification | Agent Legibility | Test Stability | Key Gaps | Last Updated |
19	|--------|-------|-------------|-----------------|---------------|----------|-------------|
20	| Document Import | - | - | - | - | - | - |
21	| Document Management | - | - | - | - | - | - |
22	| Document Indexing | - | - | - | - | - | - |
23	| Q&A Flow | - | - | - | - | - | - |
24	| Grounded Answers | - | - | - | - | - | - |
25
26	## Architectural Layers
27
28	| Layer | Grade | Boundary Enforcement | Agent Legibility | Key Gaps | Last Updated |
29	|-------|-------|---------------------|-----------------|----------|-------------|
30	| Main Process | - | - | - | - | - |
31	| Preload | - | - | - | - | - |
32	| Renderer | - | - | - | - | - |
33	| Services | - | - | - | - | - |
34
35	## Change History
36
37	### YYYY-MM-DD
38
39	- Changes:
40	- Domains promoted:
41	- Domoted:
42	- New gaps identified:
43	- Gaps closed:
44


1	# AGENTS.md
2
3	## Project
4
5	Knowledge Base - Electron + TypeScript + React desktop app for document import, indexing, and Q&A.
6
7	## Commands
8
9	- `npm run dev` - Build and launch the app
10	- `npm run check` - Type-check the codebase
11	- `npm run test` - Run tests
12
13	## Rules
14
15	- Work on one feature at a time.
16	- Run `npm run check` before committing.
17


Let me also check the shared project foundation and read a couple more project examples:


total 16
drwxr-xr-x 5 root root 133 Apr  1 11:55 .
drwxr-xr-x 9 root root 128 Apr  1 11:55 ..
drwxr-xr-x 3 root root  30 Apr  1 11:55 data
-rw-r--r-- 1 root root 799 Apr  1 11:55 package.json
drwxr-xr-x 2 root root  20 Apr  1 11:55 scripts
drwxr-xr-x 7 root root  79 Apr  1 11:55 src
-rw-r--r-- 1 root root 777 Apr  1 11:55 tsconfig.json
-rw-r--r-- 1 root root 570 Apr  1 11:55 tsconfig.node.json
-rw-r--r-- 1 root root 427 Apr  1 11:55 vite.config.ts


1	# Architecture -- Knowledge Base Electron App
2
3	## System Overview
4
5	The Knowledge Base is an Electron desktop application built with TypeScript and React. It provides document import, text indexing with chunking, and grounded question answering with citations.
6
7	## Layer Diagram
8
9	```
10	+-----------------------------------------------------------+
11	|                     Renderer (React)                       |
12	|  App.tsx -> DocumentList, DocumentDetail, QuestionPanel,  |
13	|             StatusBar, ImportPanel                         |
14	+-----------------------------------------------------------+
15	         |  window.knowledgeBase.* (typed IPC bridge)
16	+-----------------------------------------------------------+
17	|                     Preload Script                         |
18	|  contextBridge.exposeInMainWorld -> documents, indexing, qa|
19	+-----------------------------------------------------------+
20	         |  ipcRenderer.invoke(IPC_CHANNELS.*)
21	+-----------------------------------------------------------+
22	|                     Main Process                           |
23	|  main.ts -> createWindow(), initializeServices()          |
24	|  ipc-handlers.ts -> registerIpcHandlers()                  |
25	+-----------------------------------------------------------+
26	         |  Service method calls
27	+-----------------------------------------------------------+
28	|                     Services Layer                         |
29	|  DocumentService | IndexingService | QaService             |
30	|  PersistenceService (filesystem I/O)                       |
31	+-----------------------------------------------------------+
32	```
33
34	## Electron Layers
35
36	### Main Process (`src/main/`)
37
38	The main process is the Node.js process that manages the application lifecycle. Responsibilities:
39
40	- **Window management**: Creates `BrowserWindow` instances with secure web preferences (`contextIsolation: true`, `nodeIntegration: false`).
41	- **IPC registration**: Maps IPC channel names to service methods via `registerIpcHandlers()`.
42	- **Service initialization**: Constructs `PersistenceService`, `DocumentService`, `IndexingService`, and `QaService` with dependency injection.
43
44	**Key invariant**: The main process never imports React or renderer code.
45
46	### Preload (`src/preload/`)
47
48	The preload script runs in the renderer context before any page scripts load. It uses Electron's `contextBridge` to expose a limited, typed API:
49
50	```typescript
51	window.knowledgeBase = {
52	  documents: { list, import, get, delete },
53	  indexing:   { start, status, chunks },
54	  qa:         { ask, history },
55	}
56	```
57
58	**Key invariant**: The preload bridge is the only communication channel between renderer and main. No Node.js modules are accessible from the renderer.
59
60	### Renderer (`src/renderer/`)
61
62	The renderer is a React 18 application bundled by Vite. Components:
63
64	- `App.tsx` -- Root layout with header, sidebar, main panel, and status bar.
65	- `DocumentList` -- Sidebar listing of imported documents.
66	- `DocumentDetail` -- Shows document metadata, chunks, and indexing controls.
67	- `ImportPanel` -- File input for importing .txt and .md documents.
68	- `QuestionPanel` -- Text input for asking questions.
69	- `StatusBar` -- Shows index status and document count.
70
71	**Key invariant**: Renderer code never imports `fs`, `path`, `electron`, or any Node.js module.
72
73	### Services (`src/services/`)
74
75	Business logic classes running in the main process:
76
77	- `PersistenceService` -- Low-level JSON/text file I/O with atomic writes.
78	- `DocumentService` -- Document CRUD operations (import, list, get, update, delete).
79	- `IndexingService` -- Paragraph-aware chunking (~500 chars per chunk) and index management.
80	- `QaService` -- Mock question answering with keyword-based retrieval and citation generation.
81
82	**Key invariant**: Services may import shared types but never renderer code.
83
84	## Data Flow
85
86	1. User interacts with a React component (e.g., clicks "Ask").
87	2. Component calls `window.knowledgeBase.qa.ask(question)`.
88	3. Preload bridge invokes `ipcRenderer.invoke('qa:ask', question)`.
89	4. Main process IPC handler delegates to `QaService.ask()`.
90	5. QaService retrieves chunks, scores by keyword overlap, generates answer.
91	6. Response flows back through IPC to the renderer.
92	7. React component updates state and re-renders.
93
94	## Build Pipeline
95
96	1. `tsc -p tsconfig.node.json` compiles main, preload, shared, and services to `dist/`.
97	2. `vite build` bundles the renderer React app to `dist/renderer/`.
98	3. Electron loads `dist/main/main.js` as the entry point.
99
100	## Data Storage
101
102	All user data is stored under `app.getPath('userData')/knowledge-base-data/`:
103
104	```
105	knowledge-base-data/
106	  documents-meta.json     # Document metadata array
107	  content/
108	    <doc-id>.txt          # Extracted text content per document
109	  chunks/
110	    <doc-id>.json         # Chunk array per document
111	  index/
112	    index-meta.json       # Mapping of document IDs to chunk IDs
113	  qa-history.json         # Q&A interaction log
114	```
115


1	# Clean State Checklist
2
3	Run this checklist before committing and at the end of each session.
4
5	## Build
6
7	- [ ] `npm run check` passes with no type errors
8	- [ ] `npm run build` completes successfully
9
10	## Architecture
11
12	- [ ] `bash scripts/check-architecture.sh` passes with no violations
13	- [ ] No `fs` or `path` imports in renderer code
14	- [ ] No Electron IPC in service code
15	- [ ] No React imports in services or main process
16
17	## Runtime
18
19	- [ ] Application starts without errors (`npm run dev`)
20	- [ ] Structured log output appears in console at startup
21	- [ ] Document import works (check logs for IMPORT_DOCUMENT event)
22	- [ ] Indexing works for documents of all sizes
23	- [ ] Q&A returns answers with citations (check logs for ASK_QUESTION event)
24
25	## Data Integrity
26
27	- [ ] No empty chunks in indexed documents (verify with GET_CHUNKS)
28	- [ ] Q&A history persists across restarts
29	- [ ] Document metadata is consistent with actual files
30
31	## Repository
32
33	- [ ] No unintended files in git status
34	- [ ] No sensitive data (.env, credentials) staged
35	- [ ] `claude-progress.md` updated with current state
36	- [ ] `feature_list.json` reflects actual feature status
37


1	# ARCHITECTURE.md
2
3	This file is the top-level map of the system. It should stay concise and point
4	to deeper documents when needed.
5
6	## System Shape
7
8	- Product: `[replace with product name]`
9	- Primary user workflow: `[replace with main workflow]`
10	- Runtime surfaces: `[desktop / web / cli / services / workers]`
11	- Source of truth for product behavior: `docs/product-specs/`
12
13	## Domain Map
14
15	| Domain | Purpose | Primary Entry Points | Related Spec |
16	|--------|---------|----------------------|--------------|
17	| `[domain-a]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |
18	| `[domain-b]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |
19
20	## Layer Model
21
22	Use a fixed directional model so agents do not invent ad hoc architecture:
23
24	`Types -> Config -> Repo -> Service -> Runtime -> UI`
25
26	Cross-cutting concerns should enter through explicit provider or adapter
27	boundaries instead of reaching across layers directly.
28
29	## Hard Dependency Rules
30
31	- Lower layers must not depend on higher layers.
32	- UI must not bypass runtime or service contracts.
33	- Data access must enter through repositories or equivalent adapters.
34	- Shared utilities must remain generic and must not accumulate domain logic.
35	- New dependencies should be justified in the matching plan or design doc.
36
37	## Cross-Cutting Interfaces
38
39	| Concern | Approved Boundary | Notes |
40	|--------|-------------------|-------|
41	| Logging and tracing | `[provider / utility path]` | `[structured only, no ad hoc console use]` |
42	| Auth | `[provider path]` | `[token/session rules]` |
43	| External APIs | `[client or provider path]` | `[rate limit / retry guidance]` |
44	| Feature flags | `[flag boundary]` | `[ownership]` |
45
46	## Current Hot Spots
47
48	- `[area that is hardest for agents to change safely]`
49	- `[area with weak boundaries or fragile tests]`
50
51	## Change Checklist
52
53	When you touch architecture-relevant code:
54
55	1. Update this file if the domain map or allowed boundaries changed.
56	2. Update the related design doc in `docs/design-docs/` if the reasoning changed.
57	3. Add or update an executable check if the rule should be enforced mechanically.
58


Now let me check the reference documents about harness engineering itself:


1	# Initializer Agent Playbook
2
3	Use this playbook for the first serious session in a repository, before
4	incremental feature work begins.
5
6	## Goal
7
8	Create a stable operating surface so later sessions can implement behavior
9	without re-deriving startup commands, current status, or task boundaries.
10
11	## Required Outputs
12
13	The initializer should leave behind at least these artifacts:
14
15	- a root instruction file such as `AGENTS.md` or `CLAUDE.md`
16	- a machine-readable feature surface such as `feature_list.json`
17	- a durable progress artifact such as `claude-progress.md`
18	- a standard startup helper such as `init.sh`
19	- an initial safe commit that captures the baseline scaffold
20
21	## Checklist
22
23	1. Define the standard startup path.
24	2. Define the standard verification path.
25	3. Create the progress log and record the starting state.
26	4. Decompose the work into explicit features with statuses.
27	5. Create the first clean baseline commit.
28
29	## Success Test
30
31	A fresh session with no prior chat context should be able to answer:
32
33	- what this repository does
34	- how to start it
35	- how to verify it
36	- what is unfinished
37	- what the next best step is
38


1	# Coding Agent Startup Flow
2
3	Use this at the beginning of every session after initialization is complete.
4
5	## Fixed Startup Template
6
7	1. Run `pwd` and confirm the repository root.
8	2. Read `claude-progress.md`.
9	3. Read `feature_list.json`.
10	4. Review recent commits with `git log --oneline -5`.
11	5. Run `./init.sh`.
12	6. Run a baseline smoke or end-to-end path.
13	7. If the baseline is broken, fix that first.
14	8. Select the highest-priority unfinished feature.
15	9. Work only on that feature until it is verified or explicitly blocked.
16
17	## Why This Order Matters
18
19	- `pwd` prevents accidental work in the wrong directory.
20	- progress and feature files recover durable state before new edits begin.
21	- recent commits explain what changed most recently.
22	- `init.sh` standardizes startup instead of relying on memory.
23	- baseline verification catches broken starting states before new work hides
24	  them.
25
26	## End-Of-Session Mirror
27
28	The same session should end by:
29
30	1. recording progress
31	2. updating feature state
32	3. writing a handoff if needed
33	4. committing safe work
34	5. leaving a clean restart path
35


Perfect! Let me now check for more examples and look at the project-01 files to see simpler versions:


1	# Project 01: Baseline vs Minimal Harness
2
3	比较弱 harness（仅靠 prompt）和显式 harness（规则文件 + 验证机制）对 AI 编码代理任务完成率的影响。
4
5	## 目录说明
6
7	| 目录 | 含义 |
8	|------|------|
9	| `starter/` | **起点**——只有一个模糊的 `task-prompt.md`，没有 AGENTS.md、没有 feature_list.json。这是你给代理的"弱 harness"版本。 |
10	| `solution/` | **参考实现**——相同的应用代码，但配备了完整的 harness 文件（AGENTS.md、feature_list.json、init.sh、claude-progress.md）。这是"显式 harness"版本。 |
11
12	## 使用方法
13
14	```sh
15	# 1. 用 starter（弱 harness）跑一次代理任务
16	cd starter
17	npm install
18	# 把 task-prompt.md 的内容作为 prompt 给 Claude Code / Codex
19	# 让代理尝试完成：窗口启动、文档列表、问答面板、数据目录
20
21	# 2. 用 solution（显式 harness）跑一次
22	cd ../solution
23	npm install
24	# 让代理读取 AGENTS.md，按规则执行同样的任务
25
26	# 3. 对比两次结果
27	# - 任务是否完成？
28	# - 需要重试几次？
29	# - 代理是否提前声称"完成"？
30	```
31
32	## 本项目涉及的功能
33
34	- Electron 窗口成功启动
35	- UI 显示文档列表区域
36	- UI 显示问答面板
37	- 应用创建并使用本地数据目录
38
39	## 对应课件
40
41	- [Lecture 01: 为什么强大的模型仍然会失败](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
42	- [Lecture 02: Harness 到底是什么](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
43


1	# Project 02: Agent-Readable Workspace
2
3	演示仓库可读性和显式连续性产物如何减少跨会话开发中的上下文丢失。
4
5	## 目录说明
6
7	| 目录 | 含义 |
8	|------|------|
9	| `starter/` | **起点**——基于 P1 solution 的代码，新增文档导入、详情视图、持久化功能待实现。harness 较弱：AGENTS.md 简陋，没有 session-handoff。 |
10	| `solution/` | **参考实现**——所有新功能已实现，配备完整的 workspace 文档（ARCHITECTURE.md、PRODUCT.md、session-handoff.md）。 |
11
12	## 使用方法
13
14	```sh
15	# 需要至少 2 个 agent 会话来完成
16	cd starter
17	npm install
18	# Session A: 实现文档导入和详情视图
19	# Session B: 实现持久化（观察 agent 能否快速恢复上下文）
20
21	cd ../solution
22	npm install
23	# 用完整 harness 重跑，对比会话恢复速度
24	```
25
26	## 本项目涉及的功能
27
28	- 文档导入流程（文件选择器 + IPC 传输）
29	- 文档详情视图（元数据 + 内容展示）
30	- 基本持久化（导入的文档在重启后保留）
31
32	## 对应课件
33
34	- [Lecture 03: 让仓库成为唯一的真相来源](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
35	- [Lecture 04: 拆分指令文件，而不是一个巨型文件](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
36


[中文版本 →](/zh/lectures/lecture-02-what-a-harness-actually-is/)

> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/)
> Practice project: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)

# Lecture 02. What Harness Actually Means

## What Problem Does This Lecture Solve?

The word "harness" gets thrown around a lot in AI coding agent discussions, but honestly, most people mean "a prompt file" when they say harness. That's not a harness.

This lecture gives you a precise, actionable definition. Not an academic abstraction, but a framework you can use today: a harness consists of five subsystems, each with clear responsibilities and evaluation criteria. Once you understand this framework, you can systematically diagnose "why did the agent fail again" — not by vaguely blaming the model, but by pinpointing exactly which subsystem broke down.

## Core Concepts

- **The Five-Tuple Harness**: Instructions, Tools, Environment, State, Feedback. If it's not model weights, it's harness.
- **Boundary Criterion**: If a component affects the agent's perception, actions, memory, or verification, it belongs to the harness. Simple rule: not model weights = harness.
- **Weakest-Link Principle**: The harness's overall effectiveness is determined by its weakest subsystem. Your instructions might be brilliant, but without verification feedback, the agent still won't be reliable.
- **Affordance**: Good harness design provides visible cues that suggest possible actions. Clear directory structure implies code organization, explicit verification commands imply completion criteria. Harness design IS affordance design.
- **Feedback Latency**: The time between an agent's action and the feedback it receives. Compilation errors are second-level feedback, test suites are minute-level, "bug in production" is day-level. Faster feedback means faster correction.
- **Isometric Model Control**: Keep the model fixed, systematically vary harness subsystems, measure each one's marginal contribution. This is the correct way to quantify a harness's value.

## Why This Happens

Here's an analogy. Imagine you're a newly hired engineer dropped into a project with zero documentation. No README, no comments in the code, nobody tells you how to run tests, CI config is buried somewhere. Can you write good code? Maybe, but you'll spend enormous time on "figuring out what this project is about" rather than "solving the problem."

An AI agent faces the exact same situation. And it's worse — you can at least ask a colleague. The agent can only see files you put in front of it and commands it can execute.

OpenAI's harness engineering article frames the core principle as "the repo IS the spec" — all necessary context should be in the repository, delivered through structured instruction files, explicit verification commands, and clear directory organization. Anthropic's long-running agents documentation emphasizes state persistence, explicit recovery paths, and structured progress tracking. The two companies focus on different aspects, but they're saying the same thing: **everything in the engineering infrastructure outside the model determines how much of the model's capability actually gets realized.**

Look at some concrete examples:

**Claude Code** embodies harness thinking. It reads `CLAUDE.md` from your repo (instruction subsystem), can run shell commands (tool subsystem), executes in your local environment (environment subsystem), maintains session history (state subsystem), and can run tests and see results (feedback subsystem). But if you don't tell it how to run tests, the feedback subsystem is broken.

**Cursor** follows similar logic. Its `.cursorrules` file is the instruction subsystem, the terminal is the tool subsystem, it reads your project structure and lint config for the environment subsystem. But Cursor's state management is relatively weak — close the IDE and reopen it, and the previous context is gone.

**Codex** (OpenAI's coding agent) uses git worktrees to isolate each task's runtime environment, paired with a local observability stack (logs, metrics, traces), so every change is verified in an independent environment. In repos with `AGENTS.md` and clear verification commands, it performs far better than in "bare" repos.

**AutoGPT** is the cautionary tale — lack of structured state management leads to context accumulation in long tasks, and lack of precise feedback mechanisms causes the agent to loop. Many people say AutoGPT "doesn't work," but really it's AutoGPT's harness that doesn't work.

The key insight: the same model in different harnesses can show order-of-magnitude performance differences. Anthropic's controlled experiment proves this directly: same prompt, same model (Opus 4.5), bare run 20min/$9 with broken output vs. full harness 6hr/$200 with working application.

## How to Do It Right

A harness has five subsystems. You need to make sure none of them drags the rest down.

**Instruction Subsystem (I)**: Create `AGENTS.md` (or `CLAUDE.md`) containing:
- Project overview and purpose (one sentence)
- Tech stack and versions (Python 3.11, FastAPI 0.100+, PostgreSQL 15)
- First-run commands (`make setup`, `make test`)


Excellent! Now let me create a comprehensive summary document. Let me get a few more details to be thorough:


find /root/projects/learn-harness-engineering/projects/project-0{1,2} -name "claude-progress.md" 2>/dev/null


1	# Evaluator Rubric
2
3	Use this rubric after implementation and before final acceptance.
4
5	| Category | Question | Score (0-2) | Notes |
6	| --- | --- | --- | --- |
7	| Correctness | Does the implemented behavior match the requested feature? |  |  |
8	| Verification | Did the required checks actually run, with evidence? |  |  |
9	| Scope discipline | Did the session stay inside the chosen feature scope? |  |  |
10	| Reliability | Does the result survive restart or rerun without repair? |  |  |
11	| Maintainability | Is the code and documentation clear enough for the next session? |  |  |
12	| Handoff readiness | Can a fresh session continue work from repo artifacts only? |  |  |
13
14	## Verdict
15
16	- Accept
17	- Revise
18	- Block
19
20	## Required Follow-Up
21
22	- Missing evidence:
23	- Required fixes:
24	- Next review trigger:
25


1	# claude-progress.md -- Session Log
2
3	## Project 01: Baseline vs Minimal Harness
4
5	### Session 1 -- 2026-03-30
6
7	**Duration**: ~45 minutes
8	**Goal**: Establish baseline Electron app with proper harness
9
10	**What was done**:
11	- Verified Electron window launches at 1200x800 with correct webPreferences
12	- Confirmed document list panel renders with empty state message
13	- Confirmed question panel accepts input and submits via IPC
14	- Verified PersistenceService creates data directories under userData
15	- Updated feature_list.json with all 4 features at status "pass"
16	- Wrote AGENTS.md with startup rules and layer boundaries
17	- Wrote docs/ARCHITECTURE.md describing Electron layer structure
18	- Wrote docs/PRODUCT.md describing knowledge base requirements
19
20	**Decisions**:
21	- Used constructor injection for PersistenceService to keep services testable
22	- Kept all IPC channel names in a single const object in types.ts
23	- Window title set to "Knowledge Base" for consistency
24
25	**Issues**: None
26
27	**Next session**: Proceed to Project 02 to add import, detail view, and persistence features.
28


Perfect! Now I have a comprehensive understanding. Let me compile the complete findings:

## COMPREHENSIVE EXPLORATION REPORT: Learn Harness Engineering Templates & Resources

I've conducted a thorough exploration of the harness engineering templates and resources. Here's a complete report with full file contents of representative examples:

---

### **PART 1: TEMPLATE FILES IN docs/en/resources/templates/**

These are the canonical template files that define best practices:

#### **1. CLAUDE.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/CLAUDE.md`

**Content**:
```markdown
# CLAUDE.md

You are working in a repository designed for long-running implementation work.
Prioritize reliable completion, continuity across sessions, and explicit
verification over speed.

## Operating Loop

At the start of every session:

1. Run `pwd` and confirm you are in the expected repository root.
2. Read `claude-progress.md`.
3. Read `feature_list.json`.
4. Review recent commits with `git log --oneline -5`.
5. Run `./init.sh`.
6. Check whether the baseline smoke or end-to-end path is already broken.

Then select exactly one unfinished feature and work only on that feature until
you either verify it or document why it is blocked.

## Rules

- One active feature at a time.
- Do not claim completion without runnable evidence.
- Do not rewrite the feature list to hide unfinished work.
- Do not remove or weaken tests just to make the task look complete.
- Use repository artifacts as the system of record.

## Required Files

- `feature_list.json`
- `claude-progress.md`
- `init.sh`
- `session-handoff.md` when a compact handoff is useful

## Completion Gate

A feature can move to `passing` only after the required verification succeeds
and the result is recorded.

## Before You Stop

1. Update the progress log.
2. Update the feature state.
3. Record what is still broken or unverified.
4. Commit once the repository is safe to resume.
5. Leave a clean restart path for the next session.
```

#### **2. AGENTS.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/AGENTS.md`

**Content**:
```markdown
# AGENTS.md

This repository is designed for long-running coding-agent work. The goal is not
to maximize raw code output. The goal is to leave the repo in a state where the
next session can continue without guessing.

## Startup Workflow

Before writing code:

1. Confirm the working directory with `pwd`.
2. Read `claude-progress.md` for the latest verified state and next step.
3. Read `feature_list.json` and choose the highest-priority unfinished feature.
4. Review recent commits with `git log --oneline -5`.
5. Run `./init.sh`.
6. Run the required smoke or end-to-end verification before starting new work.

If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.

## Working Rules

- Work on one feature at a time.
- Do not mark a feature complete just because code was added.
- Keep changes within the selected feature scope unless a blocker forces a
  narrow supporting fix.
- Do not silently change verification rules during implementation.
- Prefer durable repo artifacts over chat summaries.

## Required Artifacts

- `feature_list.json`: source of truth for feature state
- `claude-progress.md`: session log and current verified status
- `init.sh`: standard startup and verification path
- `session-handoff.md`: optional compact handoff for larger sessions

## Definition Of Done

A feature is done only when all of the following are true:

- the target behavior is implemented
- the required verification actually ran
- evidence is recorded in `feature_list.json` or `claude-progress.md`
- the repository remains restartable from the standard startup path

## End Of Session

Before ending a session:

1. Update `claude-progress.md`.
2. Update `feature_list.json`.
3. Record any unresolved risk or blocker.
4. Commit with a descriptive message once the work is in a safe state.
5. Leave the repo clean enough for the next session to run `./init.sh`
   immediately.
```

#### **3. feature_list.json (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/feature_list.json`

**Content**:
```json
{
  "project": "replace-with-project-name",
  "last_updated": "YYYY-MM-DD",
  "rules": {
    "single_active_feature": true,
    "passing_requires_evidence": true,
    "do_not_skip_verification": true
  },
  "status_legend": {
    "not_started": "Work has not begun.",
    "in_progress": "The feature is the current active task.",
    "blocked": "Work cannot continue until a documented blocker is resolved.",
    "passing": "Required verification has passed and evidence is recorded."
  },
  "features": [
    {
      "id": "chat-001",
      "priority": 1,
      "area": "chat",
      "title": "Create a new conversation",
      "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",
      "status": "not_started",
      "verification": [
        "Open the app.",
        "Click New Chat.",
        "Verify a new conversation appears in the sidebar.",
        "Verify the main panel shows an empty conversation state."
      ],
      "evidence": [],
      "notes": ""
    }
  ]
}
```

#### **4. init.sh (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/init.sh`

**Content**:
```bash
#!/usr/bin/env bash

set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$ROOT_DIR"

# Replace these commands with the correct commands for your repository.
INSTALL_CMD=(npm install)
VERIFY_CMD=(npm test)
START_CMD=(npm run dev)

echo "==> Working directory: $PWD"
echo "==> Syncing dependencies"
"${INSTALL_CMD[@]}"

echo "==> Running baseline verification"
"${VERIFY_CMD[@]}"

echo "==> Startup command"
printf '    %q' "${START_CMD[@]}"
printf '\n'

if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
  echo "==> Starting the app"
  exec "${START_CMD[@]}"
fi

echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."
```

#### **5. claude-progress.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/claude-progress.md`

**Content**:
```markdown
# Progress Log

## Current Verified State

- Repository root:
- Standard startup path:
- Standard verification path:
- Current highest-priority unfinished feature:
- Current blocker:

## Session Log

### Session 001

- Date:
- Goal:
- Completed:
- Verification run:
- Evidence captured:
- Commits:
- Files or artifacts updated:
- Known risk or unresolved issue:
- Next best step:

### Session 002

- Date:
- Goal:
- Completed:
- Verification run:
- Evidence captured:
- Commits:
- Files or artifacts updated:
- Known risk or unresolved issue:
- Next best step:
```

#### **6. session-handoff.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/session-handoff.md`

**Content**:
```markdown
# Session Handoff

## Verified Now

- What is currently working:
- What verification actually ran:

## Changed This Session

- Code or behavior added:
- Infrastructure or harness changes:

## Broken Or Unverified

- Known defect:
- Unverified path:
- Risk for the next session:

## Next Best Step

- Highest-priority unfinished feature:
- Why it is next:
- What counts as passing:
- What must not change during that step:

## Commands

- Startup:
- Verification:
- Focused debug command:
```

#### **7. clean-state-checklist.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/clean-state-checklist.md`

**Content**:
```markdown
# Clean State Checklist

- [ ] The standard startup path still works.
- [ ] The standard verification path still runs.
- [ ] Current progress is recorded in the progress log.
- [ ] Feature state reflects what is actually passing versus unverified.
- [ ] No half-finished step is left undocumented.
- [ ] The next session can continue without manual repair.
```

#### **8. quality-document.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/quality-document.md`

**Content**:
```markdown
# Quality Document

A quality snapshot for each product domain and architectural layer. Both agents and humans can use this document to quickly understand where the codebase is strong and where it needs work.

**Update cadence:** After each significant session, or before starting a new phase of work.

**Grading scale:**

- **A**: All verification passing, clean architecture, agent-legible, stable tests
- **B**: Verification passing, mostly clean, minor gaps in legibility or test coverage
- **C**: Partially working, known gaps, some code areas hard for agents to understand
- **D**: Not working, or major structural issues

---

## Product Domains

| Domain | Grade | Verification | Agent Legibility | Test Stability | Key Gaps | Last Updated |
|--------|-------|-------------|-----------------|---------------|----------|-------------|
| Document Import | - | - | - | - | - | - |
| Document Management | - | - | - | - | - | - |
| Document Indexing | - | - | - | - | - | - |
| Q&A Flow | - | - | - | - | - | - |
| Grounded Answers | - | - | - | - | - | - |

## Architectural Layers

| Layer | Grade | Boundary Enforcement | Agent Legibility | Key Gaps | Last Updated |
|-------|-------|---------------------|-----------------|----------|-------------|
| Main Process | - | - | - | - | - |
| Preload | - | - | - | - | - |
| Renderer | - | - | - | - | - |
| Services | - | - | - | - | - |

## Change History

### YYYY-MM-DD

- Changes:
- Domains promoted:
- Demoted:
- New gaps identified:
- Gaps closed:
```

#### **9. evaluator-rubric.md (Template)**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/templates/evaluator-rubric.md`

**Content**:
```markdown
# Evaluator Rubric

Use this rubric after implementation and before final acceptance.

| Category | Question | Score (0-2) | Notes |
| --- | --- | --- | --- |
| Correctness | Does the implemented behavior match the requested feature? |  |  |
| Verification | Did the required checks actually run, with evidence? |  |  |
| Scope discipline | Did the session stay inside the chosen feature scope? |  |  |
| Reliability | Does the result survive restart or rerun without repair? |  |  |
| Maintainability | Is the code and documentation clear enough for the next session? |  |  |
| Handoff readiness | Can a fresh session continue work from repo artifacts only? |  |  |

## Verdict

- Accept
- Revise
- Block

## Required Follow-Up

- Missing evidence:
- Required fixes:
- Next review trigger:
```

---

### **PART 2: PROJECT-SPECIFIC IMPLEMENTATIONS**

#### **Project 01 Solution: CLAUDE.md (Concrete Example)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-01/solution/CLAUDE.md`

```markdown
# CLAUDE.md -- Quick Reference for Claude Code

## Project Overview

This is an Electron + TypeScript + React knowledge base application. The codebase is structured into four layers: main process, preload, renderer, and services.

## Build & Run

```bash
npm install        # Install dependencies
npm run check      # Type-check without emitting
npm run build      # Compile main/preload + bundle renderer
npm run dev        # Build + launch Electron
```

## Key Files

| File | Purpose |
|------|---------|
| `src/main/main.ts` | Electron entry point, window creation, service wiring |
| `src/main/ipc-handlers.ts` | IPC channel registration |
| `src/preload/preload.ts` | contextBridge API exposure |
| `src/renderer/App.tsx` | Root React component |
| `src/services/*.ts` | Business logic (document, indexing, QA, persistence) |
| `src/shared/types.ts` | Shared types and IPC channel constants |
| `feature_list.json` | Feature tracking with pass/fail status |

## Architecture Rules

- Renderer never imports Node.js modules.
- All main-renderer communication goes through IPC.
- Services use constructor-injected `PersistenceService`.
- IPC channel names live in `src/shared/types.ts`.

## How to Add a Feature

1. Define the IPC channel in `src/shared/types.ts`.
2. Add the handler in `src/main/ipc-handlers.ts`.
3. Expose the API in `src/preload/preload.ts`.
4. Add the type declaration in `src/renderer/types.d.ts`.
5. Build the UI in `src/renderer/components/`.
6. Update `feature_list.json` with the result.

## Testing

```bash
npm test           # Run vitest suite
npm run test:watch # Run tests in watch mode
```
```

#### **Project 01 Solution: claude-progress.md (Concrete Example)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-01/solution/claude-progress.md`

```markdown
# claude-progress.md -- Session Log

## Project 01: Baseline vs Minimal Harness

### Session 1 -- 2026-03-30

**Duration**: ~45 minutes
**Goal**: Establish baseline Electron app with proper harness

**What was done**:
- Verified Electron window launches at 1200x800 with correct webPreferences
- Confirmed document list panel renders with empty state message
- Confirmed question panel accepts input and submits via IPC
- Verified PersistenceService creates data directories under userData
- Updated feature_list.json with all 4 features at status "pass"
- Wrote AGENTS.md with startup rules and layer boundaries
- Wrote docs/ARCHITECTURE.md describing Electron layer structure
- Wrote docs/PRODUCT.md describing knowledge base requirements

**Decisions**:
- Used constructor injection for PersistenceService to keep services testable
- Kept all IPC channel names in a single const object in types.ts
- Window title set to "Knowledge Base" for consistency

**Issues**: None

**Next session**: Proceed to Project 02 to add import, detail view, and persistence features.
```

#### **Project 02 Starter: AGENTS.md (Intermediate Example)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-02/starter/AGENTS.md`

```markdown
# AGENTS.md -- Project 02: Agent-Readable Workspace

## Quick Start

1. Run `npm install && npm run check` to verify the build.
2. Read `docs/ARCHITECTURE.md` for layer structure.
3. Check `feature_list.json` for what needs to be done.

## Layers

- Main process: `src/main/` -- window, IPC, services
- Preload: `src/preload/` -- bridge API
- Renderer: `src/renderer/` -- React UI
- Services: `src/services/` -- business logic

## Conventions

- TypeScript strict mode. No `any` without comment.
- Named exports only.
- IPC channels in `src/shared/types.ts`.
```

#### **Project 02 Starter: feature_list.json (Concrete Example)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-02/starter/feature_list.json`

```json
{
  "project": "project-02",
  "description": "Agent-readable workspace with import, detail view, and persistence",
  "features": [
    {
      "id": "window-launch",
      "name": "Window Launch",
      "description": "Electron app opens a BrowserWindow with correct dimensions and preload script",
      "status": "pass",
      "evidence": "Carried over from P1 -- verified working",
      "testedAt": "2026-03-30T10:00:00Z"
    },
    {
      "id": "document-list",
      "name": "Document List Panel",
      "description": "Left sidebar shows imported documents with empty state message",
      "status": "pass",
      "evidence": "Carried over from P1 -- verified working",
      "testedAt": "2026-03-30T10:05:00Z"
    },
    {
      "id": "question-panel",
      "name": "Question Panel",
      "description": "Bottom input bar accepts questions and submits via IPC",
      "status": "pass",
      "evidence": "Carried over from P1 -- verified working",
      "testedAt": "2026-03-30T10:08:00Z"
    },
    {
      "id": "data-directory",
      "name": "Data Directory",
      "description": "PersistenceService creates and manages userData/knowledge-base-data directory",
      "status": "pass",
      "evidence": "Carried over from P1 -- verified working",
      "testedAt": "2026-03-30T10:10:00Z"
    },
    {
      "id": "document-import",
      "name": "Document Import",
      "description": "Users can import .txt and .md files via ImportPanel with file picker",
      "status": "not-started",
      "evidence": null,
      "testedAt": null
    },
    {
      "id": "document-detail",
      "name": "Document Detail with Content",
      "description": "DocumentDetail shows full document content, metadata, and delete button",
      "status": "not-started",
      "evidence": null,
      "testedAt": null
    },
    {
      "id": "basic-persistence",
      "name": "Basic Persistence",
      "description": "Imported documents persist across app restarts via filesystem storage",
      "status": "not-started",
      "evidence": null,
      "testedAt": null
    }
  ]
}
```

#### **Project 03 Starter: AGENTS.md (Advanced Example)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-03/starter/AGENTS.md`

```markdown
# AGENTS.md -- Project 03: Scope Control and Grounded Verification

## Quick Start

1. Run `npm install && npm run check` to verify the build.
2. Read `docs/ARCHITECTURE.md` for layer structure.
3. Read `docs/PRODUCT.md` for feature requirements.
4. Check `feature_list.json` for what needs to be done.

## Layers

- Main: `src/main/` -- window, IPC, services
- Preload: `src/preload/` -- bridge API
- Renderer: `src/renderer/` -- React UI
- Services: `src/services/` -- business logic

## Conventions

- TypeScript strict mode. No `any` without comment.
- Named exports only.
- IPC channels in `src/shared/types.ts`.

## Features to Implement

The new features for this project are:

1. **Document Chunking** -- IndexingService splits documents into ~500 char chunks
2. **Metadata Extraction** -- Extract word count, line count, file type on import
3. **Indexing Status UI** -- StatusBar shows indexing progress with counts
4. **Grounded Q&A** -- QaService returns answers with citations and confidence

Check `feature_list.json` for current status.

## Definition of Done

A feature is "done" when:

1. TypeScript compiles without errors (`npm run check`).
2. The app launches and the feature works.
3. The feature appears in `feature_list.json` with status `"pass"` and evidence.

## Session Handoff

When resuming work, read `session-handoff.md` for context from the previous session.
```

#### **Project 05 Starter: AGENTS.md (With Observability)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-05/starter/AGENTS.md`

```markdown
# AGENTS.md

This repository is designed for long-running coding-agent work. The goal is not
to maximize raw code output. The goal is to leave the repo in a state where the
next session can continue without guessing.

## Startup Workflow

Before writing code:

1. Confirm the working directory with `pwd`.
2. Read `claude-progress.md` for the latest verified state and next step.
3. Read `feature_list.json` and choose the highest-priority unfinished feature.
4. Review recent commits with `git log --oneline -5`.
5. Run `./init.sh`.
6. Run the required smoke or end-to-end verification before starting new work.

If baseline verification is already failing, fix that first. Do not stack new
feature work on top of a broken starting state.

## Working Rules

- Work on one feature at a time.
- Do not mark a feature complete just because code was added.
- Keep changes within the selected feature scope unless a blocker forces a
  narrow supporting fix.
- Do not silently change verification rules during implementation.
- Prefer durable repo artifacts over chat summaries.

## Runtime Observability

All services use structured logging via `src/services/logger.ts`. Log output is
JSON-formatted with timestamp, level, service name, and message. Log levels:
DEBUG, INFO, WARN, ERROR.

When debugging, check logs for:
- Service initialization events at startup
- IPC channel invocations and their parameters
- Indexing chunk counts and content lengths
- Q&A confidence scores and citation counts

## Architecture Constraints

The following layer boundaries are enforced by `scripts/check-architecture.sh`:

- **Renderer** must not import `fs`, `path`, or any Node.js core modules.
- **Services** must not import Electron IPC or renderer-specific modules.
- **Preload** must only expose the typed API via contextBridge.

Run `bash scripts/check-architecture.sh` before committing.

## Required Artifacts

- `feature_list.json`: source of truth for feature state
- `claude-progress.md`: session log and current verified status
- `init.sh`: standard startup and verification path
- `session-handoff.md`: optional compact handoff for larger sessions
- `clean-state-checklist.md`: pre-commit repository health check

## Definition Of Done

A feature is done only when all of the following are true:

- the target behavior is implemented
- the required verification actually ran
- evidence is recorded in `feature_list.json` or `claude-progress.md`
- the repository remains restartable from the standard startup path
- `scripts/check-architecture.sh` passes with no violations

## End Of Session

Before ending a session:

1. Update `claude-progress.md`.
2. Update `feature_list.json`.
3. Record any unresolved risk or blocker.
4. Run `bash scripts/check-architecture.sh`.
5. Commit with a descriptive message once the work is in a safe state.
6. Leave the repo clean enough for the next session to run `./init.sh`
   immediately.
```

#### **Project 05 Starter: clean-state-checklist.md (Extended Example)**
**Location**: `/root/projects/learn-harness-engineering/projects/project-05/starter/clean-state-checklist.md`

```markdown
# Clean State Checklist

Run this checklist before committing and at the end of each session.

## Build

- [ ] `npm run check` passes with no type errors
- [ ] `npm run build` completes successfully

## Architecture

- [ ] `bash scripts/check-architecture.sh` passes with no violations
- [ ] No `fs` or `path` imports in renderer code
- [ ] No Electron IPC in service code
- [ ] No React imports in services or main process

## Runtime

- [ ] Application starts without errors (`npm run dev`)
- [ ] Structured log output appears in console at startup
- [ ] Document import works (check logs for IMPORT_DOCUMENT event)
- [ ] Indexing works for documents of all sizes
- [ ] Q&A returns answers with citations (check logs for ASK_QUESTION event)

## Data Integrity

- [ ] No empty chunks in indexed documents (verify with GET_CHUNKS)
- [ ] Q&A history persists across restarts
- [ ] Document metadata is consistent with actual files

## Repository

- [ ] No unintended files in git status
- [ ] No sensitive data (.env, credentials) staged
- [ ] `claude-progress.md` updated with current state
- [ ] `feature_list.json` reflects actual feature status
```

---

### **PART 3: ADVANCED TEMPLATES - OpenAI Advanced Pack**

#### **OpenAI Advanced Template: AGENTS.md**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/openai-advanced/repo-template/AGENTS.md`

```markdown
# AGENTS.md

This repository is optimized for long-running coding-agent work. Keep this file
short. Use it as the routing layer into the system-of-record docs, not as a
giant instruction dump.

## Startup Workflow

Before changing code:

1. Confirm the repo root with `pwd`.
2. Read `ARCHITECTURE.md` for the current system map and hard dependency rules.
3. Read `docs/QUALITY_SCORE.md` to see which domains or layers are weakest.
4. Read `docs/PLANS.md`, then open the active plan you are working from.
5. Read the relevant product spec in `docs/product-specs/`.
6. Run the standard bootstrap and verification path for this repo.
7. If baseline verification is failing, repair the baseline before adding scope.

## Routing Map

- `ARCHITECTURE.md`: domain map, layer model, dependency rules
- `docs/design-docs/index.md`: design decisions and core beliefs
- `docs/product-specs/index.md`: current product behaviors and acceptance targets
- `docs/PLANS.md`: plan lifecycle and execution-plan policy
- `docs/QUALITY_SCORE.md`: product-domain and layer health
- `docs/RELIABILITY.md`: runtime signals, benchmarks, and restart expectations
- `docs/SECURITY.md`: secrets, sandbox, data, and external-action rules
- `docs/FRONTEND.md`: UI constraints, design system rules, accessibility checks

## Working Contract

- Work from one bounded plan or feature slice at a time.
- Do not mark work done from code inspection alone; runnable evidence is
  required.
- If you change behavior, update the matching product, plan, or reliability
  docs in the same session.
- If you see repeated review feedback, promote it into a mechanical rule, check,
  or linter instead of re-explaining it in chat.
- Keep generated material in `docs/generated/` and source references in
  `docs/references/`.
- Prefer adding small, current docs over growing this file.

## Definition Of Done

A change is done only when all of the following are true:

- target behavior is implemented
- required verification actually ran
- evidence is linked from the relevant plan or quality document
- affected docs remain current
- the repository can restart cleanly from the standard startup path

## End Of Session

Before ending a session:

1. Update the active execution plan.
2. Update `docs/QUALITY_SCORE.md` if any domain or layer meaningfully changed.
3. Record new debt in `docs/exec-plans/tech-debt-tracker.md` if you deferred it.
4. Move finished plans to `docs/exec-plans/completed/` when appropriate.
5. Leave the repo in a restartable state with a clear next action.
```

#### **OpenAI Advanced Template: ARCHITECTURE.md**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/openai-advanced/repo-template/ARCHITECTURE.md`

```markdown
# ARCHITECTURE.md

This file is the top-level map of the system. It should stay concise and point
to deeper documents when needed.

## System Shape

- Product: `[replace with product name]`
- Primary user workflow: `[replace with main workflow]`
- Runtime surfaces: `[desktop / web / cli / services / workers]`
- Source of truth for product behavior: `docs/product-specs/`

## Domain Map

| Domain | Purpose | Primary Entry Points | Related Spec |
|--------|---------|----------------------|--------------|
| `[domain-a]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |
| `[domain-b]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |

## Layer Model

Use a fixed directional model so agents do not invent ad hoc architecture:

`Types -> Config -> Repo -> Service -> Runtime -> UI`

Cross-cutting concerns should enter through explicit provider or adapter
boundaries instead of reaching across layers directly.

## Hard Dependency Rules

- Lower layers must not depend on higher layers.
- UI must not bypass runtime or service contracts.
- Data access must enter through repositories or equivalent adapters.
- Shared utilities must remain generic and must not accumulate domain logic.
- New dependencies should be justified in the matching plan or design doc.

## Cross-Cutting Interfaces

| Concern | Approved Boundary | Notes |
|--------|-------------------|-------|
| Logging and tracing | `[provider / utility path]` | `[structured only, no ad hoc console use]` |
| Auth | `[provider path]` | `[token/session rules]` |
| External APIs | `[client or provider path]` | `[rate limit / retry guidance]` |
| Feature flags | `[flag boundary]` | `[ownership]` |

## Current Hot Spots

- `[area that is hardest for agents to change safely]`
- `[area with weak boundaries or fragile tests]`

## Change Checklist

When you touch architecture-relevant code:

1. Update this file if the domain map or allowed boundaries changed.
2. Update the related design doc in `docs/design-docs/` if the reasoning changed.
3. Add or update an executable check if the rule should be enforced mechanically.
```

---

### **PART 4: REFERENCE DOCUMENTS - Harness Engineering Best Practices**

#### **Initializer Agent Playbook**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/reference/initializer-agent-playbook.md`

```markdown
# Initializer Agent Playbook

Use this playbook for the first serious session in a repository, before
incremental feature work begins.

## Goal

Create a stable operating surface so later sessions can implement behavior
without re-deriving startup commands, current status, or task boundaries.

## Required Outputs

The initializer should leave behind at least these artifacts:

- a root instruction file such as `AGENTS.md` or `CLAUDE.md`
- a machine-readable feature surface such as `feature_list.json`
- a durable progress artifact such as `claude-progress.md`
- a standard startup helper such as `init.sh`
- an initial safe commit that captures the baseline scaffold

## Checklist

1. Define the standard startup path.
2. Define the standard verification path.
3. Create the progress log and record the starting state.
4. Decompose the work into explicit features with statuses.
5. Create the first clean baseline commit.

## Success Test

A fresh session with no prior chat context should be able to answer:

- what this repository does
- how to start it
- how to verify it
- what is unfinished
- what the next best step is
```

#### **Coding Agent Startup Flow**
**Location**: `/root/projects/learn-harness-engineering/docs/en/resources/reference/coding-agent-startup-flow.md`

```markdown
# Coding Agent Startup Flow

Use this at the beginning of every session after initialization is complete.

## Fixed Startup Template

1. Run `pwd` and confirm the repository root.
2. Read `claude-progress.md`.
3. Read `feature_list.json`.
4. Review recent commits with `git log --oneline -5`.
5. Run `./init.sh`.
6. Run a baseline smoke or end-to-end path.
7. If the baseline is broken, fix that first.
8. Select the highest-priority unfinished feature.
9. Work only on that feature until it is verified or explicitly blocked.

## Why This Order Matters

- `pwd` prevents accidental work in the wrong directory.
- progress and feature files recover durable state before new edits begin.
- recent commits explain what changed most recently.
- `init.sh` standardizes startup instead of relying on memory.
- baseline verification catches broken starting states before new work hides
  them.

## End-Of-Session Mirror

The same session should end by:

1. recording progress
2. updating feature state
3. writing a handoff if needed
4. committing safe work
5. leaving a clean restart path
```

---

### **PART 5: ARCHITECTURE DOCUMENTATION EXAMPLE**

#### **Project 02: Architecture Documentation**
**Location**: `/root/projects/learn-harness-engineering/projects/project-02/starter/docs/ARCHITECTURE.md`

```markdown
# Architecture -- Knowledge Base Electron App

## System Overview

The Knowledge Base is an Electron desktop application built with TypeScript and React. It provides document import, text indexing with chunking, and grounded question answering with citations.

## Layer Diagram

```
+-----------------------------------------------------------+
|                     Renderer (React)                       |
|  App.tsx -> DocumentList, DocumentDetail, QuestionPanel,  |
|             StatusBar, ImportPanel                         |
+-----------------------------------------------------------+
         |  window.knowledgeBase.* (typed IPC bridge)
+-----------------------------------------------------------+
|                     Preload Script                         |
|  contextBridge.exposeInMainWorld -> documents, indexing, qa|
+-----------------------------------------------------------+
         |  ipcRenderer.invoke(IPC_CHANNELS.*)
+-----------------------------------------------------------+
|                     Main Process                           |
|  main.ts -> createWindow(), initializeServices()          |
|  ipc-handlers.ts -> registerIpcHandlers()                  |
+-----------------------------------------------------------+
         |  Service method calls
+-----------------------------------------------------------+
|                     Services Layer                         |
|  DocumentService | IndexingService | QaService             |
|  PersistenceService (filesystem I/O)                       |
+-----------------------------------------------------------+
```

## Electron Layers

### Main Process (`src/main/`)

The main process is the Node.js process that manages the application lifecycle. Responsibilities:

- **Window management**: Creates `BrowserWindow` instances with secure web preferences (`contextIsolation: true`, `nodeIntegration: false`).
- **IPC registration**: Maps IPC channel names to service methods via `registerIpcHandlers()`.
- **Service initialization**: Constructs `PersistenceService`, `DocumentService`, `IndexingService`, and `QaService` with dependency injection.

**Key invariant**: The main process never imports React or renderer code.

### Preload (`src/preload/`)

The preload script runs in the renderer context before any page scripts load. It uses Electron's `contextBridge` to expose a limited, typed API:

```typescript
window.knowledgeBase = {
  documents: { list, import, get, delete },
  indexing:   { start, status, chunks },
  qa:         { ask, history },
}
```

**Key invariant**: The preload bridge is the only communication channel between renderer and main. No Node.js modules are accessible from the renderer.

### Renderer (`src/renderer/`)

The renderer is a React 18 application bundled by Vite. Components:

- `App.tsx` -- Root layout with header, sidebar, main panel, and status bar.
- `DocumentList` -- Sidebar listing of imported documents.
- `DocumentDetail` -- Shows document metadata, chunks, and indexing controls.
- `ImportPanel` -- File input for importing .txt and .md documents.
- `QuestionPanel` -- Text input for asking questions.
- `StatusBar` -- Shows index status and document count.

**Key invariant**: Renderer code never imports `fs`, `path`, `electron`, or any Node.js module.

### Services (`src/services/`)

Business logic classes running in the main process:

- `PersistenceService` -- Low-level JSON/text file I/O with atomic writes.
- `DocumentService` -- Document CRUD operations (import, list, get, update, delete).
- `IndexingService` -- Paragraph-aware chunking (~500 chars per chunk) and index management.
- `QaService` -- Mock question answering with keyword-based retrieval and citation generation.

**Key invariant**: Services may import shared types but never renderer code.

## Data Flow

1. User interacts with a React component (e.g., clicks "Ask").
2. Component calls `window.knowledgeBase.qa.ask(question)`.
3. Preload bridge invokes `ipcRenderer.invoke('qa:ask', question)`.
4. Main process IPC handler delegates to `QaService.ask()`.
5. QaService retrieves chunks, scores by keyword overlap, generates answer.
6. Response flows back through IPC to the renderer.
7. React component updates state and re-renders.

## Build Pipeline

1. `tsc -p tsconfig.node.json` compiles main, preload, shared, and services to `dist/`.
2. `vite build` bundles the renderer React app to `dist/renderer/`.
3. Electron loads `dist/main/main.js` as the entry point.

## Data Storage

All user data is stored under `app.getPath('userData')/knowledge-base-data/`:

```
knowledge-base-data/
  documents-meta.json     # Document metadata array
  content/
    <doc-id>.txt          # Extracted text content per document
  chunks/
    <doc-id>.json         # Chunk array per document
  index/
    index-meta.json       # Mapping of document IDs to chunk IDs
  qa-history.json         # Q&A interaction log
```
```

---

### **SUMMARY OF KEY PATTERNS**

**The Five Essential Harness Artifacts**:

1. **CLAUDE.md** or **AGENTS.md** — Root instruction file with startup workflow and completion rules
2. **feature_list.json** — Machine-readable feature state with verification checklist
3. **claude-progress.md** — Session log documenting state, decisions, and next steps
4. **init.sh** — Standard startup automation (install → verify → run)
5. **session-handoff.md** — Optional but recommended for complex projects

**Harness Subsystems** (from the course):

1. **Instructions** — AGENTS.md, CLAUDE.md, ARCHITECTURE.md
2. **Tools** — Shell commands, npm scripts, build pipelines
3. **Environment** — Directory structure, type definitions, shared constants
4. **State** — feature_list.json, claude-progress.md, git history
5. **Feedback** — Verification commands, logs, test output

**Critical Rules**:

- **One feature at a time** — Never stack new work on broken baselines
- **Verification is mandatory** — No feature complete without runnable evidence
- **Repository is system of record** — Never rely on chat history alone
- **Session continuity** — Every session must leave clear handoff for the next
- **Clean state** — Before committing, verify startup path still works

All files are in absolute paths starting from `/root/projects/learn-harness-engineering/`