CodeHero Developer Training — The Autonomous Development Framework (ADF)

Version 1.0 · September 2026 · For CodeHero PRO 4.48 and later

Source: ADF_TRAINING_GUIDE.md · Spec Builder knowledge file: CODEHERO_PLANNING_GUIDE.md

This is the training course for developers who will design, configure and operate CodeHero projects. It teaches the Autonomous Development Framework (ADF): the method CodeHero implements, in which AI agents build, test and document a product from a specification while humans provide only what nobody else can — the business truth, the credentials, and the approvals.

The course is written in English so it can be shared with any team. Trainees may speak Greek or English with the platform; CodeHero replies in the user's language.

---

How to use this course

Who it is for. Developers, analysts and technical project managers who will:

1. extract requirements from a client and turn them into a specification package;
2. plan a CodeHero project (tickets, roles, providers, execution settings);
3. operate the run (read reports, answer questions, unblock tickets, verify results);
4. adapt the framework itself by editing the global context and the project contexts.

Prerequisites. Basic web development knowledge (HTTP, HTML, a backend language, SQL). A working CodeHero PRO installation with at least two active AI providers (one vision-capable). Read the User Guide chapters 2, 6, 8, 9, 11, 13, 14 and 15 first — this course assumes you know the UI.

Structure. Eight modules, in the order the work happens in real life. Each module ends with Exercises; Module 8 is a capstone with a grading rubric. Suggested pace: one module per half-day, capstone on day five.

Files this course refers to. All paths are relative to the CodeHero source tree (/home/claude/codehero/ on a development machine) or the installed tree (/opt/codehero/ and /etc/codehero/ on a server).

Keep these files open while you study. The course explains them; it does not replace them.

Presentations. The website carries slide decks with speaker notes at presentations/. The first one, The Domain Expert's Software Factory, tells the story of this course to business people with no technical background (interview → approval → build and verification → handoff, with the RepairFlow example of Modules 2–7). Use it to open a client workshop or to brief the domain experts you will interview; the developer material stays here.

---

PART I — FOUNDATIONS

Module 1 — The framework: what ADF is and how CodeHero implements it

1.1 The one-sentence definition

CodeHero is a complete implementation of that idea: a platform (web UI, daemon, agent, tools, database, containers) plus a written method (the global context, the Spec Builder guide, the planner). This course teaches the method; the User Guide teaches the platform.

1.2 Why a framework at all

Give a strong model a task and it will write code. That is not the problem. The problems appear in the second hour:

• it guesses a business rule (a discount, a permission, a deadline) and builds the wrong product with confidence;
• it claims success ("this should work now") without loading the page;
• it loses its memory when the context window fills, and repeats or contradicts earlier work;
• it breaks something that worked while fixing something else;
• it weakens a protection (turns off validation, hand-inserts a row) to make a test pass;
• two agents working at once edit the same file and corrupt each other's work.

Every rule in ADF exists because one of these happened in a real run. The framework is not theory; it is the accumulated set of guardrails from production deliveries. When you later customize the contexts (Module 6), remember that: change a rule only when you know which failure it prevents.

1.3 The twelve principles

These are the principles behind the global context (config/global-context.md). Learn them by name; the rest of the course refers back to them.

A useful mental test when you evaluate a plan, a context change or a ticket: which principle does this serve, and which one does it risk?

1.4 The pipeline: from client conversation to verified software

 CLIENT (domain expert)
      │  interview, one question at a time, four statuses
      ▼
 SPEC BUILDER  (claude.ai / ChatGPT project + CODEHERO_PLANNING_GUIDE.md)
      │  specification package: header + codehero_environment + run settings
      │  + registers (requirements, decisions, dependencies) + ticket plan
      ▼
 PLAN WITH AI  (in-app planner, config/assistant-planner.md)
      │  writes the specification with the user or imports the package,
      │  shows preview → operator confirms → creates project + ONE [PLAN] ticket
      ▼
 PLANNING TICKET  ([PLAN] … in PLAN MODE, guides/planning.md, on the real installation)
      │  baseline → requirements → contracts → dry run → review rounds → peer check
      │  → assigns providers → creates the FIRST PHASE of tickets (last one: [REPLAN])
      ▼

 DAEMON + AGENT  (codehero-daemon → HeroAgent or CLI provider, per ticket)
      │  global context + project context + ticket → build → verify → report
      │  SPEC FILES (.specs/) + KNOWLEDGE BASE (graph) + git snapshots
      ▼
 VERIFY / FIX / REPLAN tickets  (different provider, master + ultra)
      │
      ▼
 HANDOFF REPORT → operator → client   (works+evidence · waiting on you · decided for you · open)

Three "brains" take part, and it matters which one you are talking to:

The Spec Builder is deliberately outside the platform: it needs a long, calm conversation with a business person, file uploads, and no server access. The other two live inside CodeHero because they need the installation's real facts (active providers, ports, containers).

1.5 The machinery (enough to reason about it)

You do not need to read the source to operate CodeHero, but you must know what runs where, because every question in Module 5 ("why did it stop?") comes back to one of these parts.

Ports 9453 and 9867 are the defaults; the real values come from /etc/codehero/system.conf (ADMIN_PORT, PROJECTS_PORT) and are substituted into the context as {ADMIN_PORT} and {PROJECTS_PORT}.

1.6 The layers of instruction

When a ticket runs, the agent's system prompt is assembled from layers, in this order (see build_project_context_file() in the daemon):

1. === CURRENT WORKING PROJECT === — project id, name, ticket id; the isolation stamp ("pass project_id=<id> to every codehero_* tool").
2. A knowledge-graph snapshot — the most relevant nodes of the project's knowledge base.
3. === PROJECT GLOBAL CONTEXT === — the project's stored copy of the global context, placeholders resolved.
4. === PROJECT CONTEXT === — the project's stored copy of the language/stack context.
5. === PROJECT DESCRIPTION === and === PROJECT INFO === — the description and the free "additional notes" field of the project.
6. === RUNTIME ENVIRONMENT === — pinned runtime versions ("already installed — do NOT reinstall").
7. === SERVER PORTS === — the concrete preview URL.
8. === PROJECT SERVICES === — databases, caches and web apps with localhost:<port> and credentials ("already installed and running").
9. Container execution rules and the container app-deployment guide (container projects only).
10. Smart-context material — project map, prior extraction summaries, recent history.

Then the user-turn prompt adds: project paths, the database block, the ticket's own context, the parent ticket chain, the ticket title and description, the allowed write paths, and the completion contract ("end your final message with TASK COMPLETED: <summary>").

Two consequences you will use constantly:

• Precedence is by specificity. The global context sets the method; the language context sets the stack idioms and must defer to the global for shared rules; the project context and the ticket carry the facts of this project. A ticket description can add facts; it should never contradict the method.
• Contexts are copied per project at creation. Editing config/global-context.md changes new projects. An existing project keeps its stored copy until you edit it in Project Settings → Context or load the defaults again (Module 6).

1.7 Glossary you must know before Module 2

Exercises — Module 1

1. Open config/global-context.md. For each of the twelve principles, find the exact section and copy one sentence that states it. (You will need these citations in Module 6.)
2. Read the glossary table in §0 of the global context. Explain in your own words the difference between the SPEC FILE and the KNOWLEDGE BASE, and why the framework keeps both.
3. On your training installation, open Settings and list the active providers. Mark which ones have vision. Keep this list; every plan in Modules 4 and 8 must respect it.
4. In the daemon's log (journalctl -u codehero-daemon -f) watch one ticket run from start to finish. Write down the sequence of statuses you observed.

---

PART II — EXTRACTING KNOWLEDGE FROM THE CLIENT

Module 2 — The Spec Builder interview and the specification package

2.1 The problem this module solves

The most expensive mistakes in software are made before the first line of code: a misunderstood process, an unstated rule, a wish mistaken for a capability. In ADF the build is autonomous, so there is no developer in the loop to notice a misunderstanding half-way. Everything the agents will need must be extracted from the client before the run, in a form the agents can use.

The Spec Builder does that. It is not a form; it is an interviewer with a method, and the developer's job is to run it well, review its output critically, and know when it is done.

2.2 Setting it up

1. Create a project in claude.ai (or a ChatGPT project). Upload docs/CODEHERO_PLANNING_GUIDE.md as project knowledge.
2. Set the project instruction to exactly: "You are the CodeHero Spec Builder. Follow the file CODEHERO_PLANNING_GUIDE.md exactly."
3. Start the conversation with the client's material (spreadsheets, screenshots, the current manual) already uploaded, so the assistant reads them before asking anything.

Who sits at the keyboard? Two working arrangements are common:

• The client types. The Spec Builder was written for a domain expert with no technical background: one question per message, no jargon, a proposed answer whenever it has a basis for one. You review the transcript and the package afterwards.
• You type, with the client next to you (or on a call). Faster for small tools; you can rephrase the assistant's question in the client's own words and keep it on track. You must resist the temptation to answer business questions yourself.

Either way, the developer never invents a business fact. That rule binds you exactly as it binds the agents (P3, P10).

2.3 The four statuses — the backbone of the whole method

Every requirement and every decision in the package carries one status and one origin:

Origin is user, document or agent. A requirement the assistant proposed and the client approved is Confirmed / agent. The origin column is what lets the client later audit "what did I ask for, and what did you add?".

Two rules make the statuses honest:

• "I don't know" is an answer. A technical gap is filled silently as Technical. A business gap becomes Assumed, with one sentence saying what was assumed.
• Critical items are never silently assumed. Anything that decides money, approvals, deletion rights, legal or compliance obligations, or safety stays Open and visible in every summary until the client confirms it — even when the client wants to finish quickly.

You will see the same distinction again at run time: the agent's SAFE DEFAULT (P5) is exactly an Assumed item chosen so that it cannot hurt anyone, and CRITICAL questions stop the ticket instead of getting a default.

2.4 The interview, stage by stage

Part 2 of the Planning Guide is a coverage checklist, not a script. The assistant asks in the order the conversation makes natural, skips what a document already answers, and adapts wording to the industry. As the developer, you check coverage at the end: did every stage get answered or consciously defaulted?

Note the two mandatory checkpoints. Stage C comes before any technology decision, because the constraints — not the archetype — decide the stack (Module 3). Stage P comes before scale, brand and security, because a misunderstanding caught at the preview costs one message and the same misunderstanding caught after the build costs dozens of tickets.

2.5 A worked interview: "RepairFlow"

We will follow one example through the whole course. A small electronics repair company with three technicians tracks repair jobs in an Excel sheet. Jobs get lost, deadlines are missed, and the owner cannot see who is doing what.

The opening question is always the same: "Which piece of your work do you want to organize or automate? Describe a real example — what happened last time, step by step."

Extracts from the transcript, with the status the Spec Builder assigned:

Then the preview (Stage P). The assistant showed the job list as a text wireframe (columns, the three most common actions: new job, change status, print job sheet), walked the client's own laptop example through the states, described the three roles in one line each (Owner sees all and gives discounts; Technician sees own jobs and changes status; Front desk creates jobs and marks delivered), and listed what was Confirmed, Assumed and Open. The client corrected one thing: the front desk also takes the payment, so Front desk may mark a job paid. One message, one correction, dozens of tickets saved.

2.6 The spreadsheet intake procedure

When the client uploads a spreadsheet (most internal tools start as one), the Spec Builder follows §2.9 of the guide before asking Stage 2 questions. Learn the mapping; you will use it yourself when a client hands you an Excel file:

Two habits protect you: record separately what the sheet does today and what the new application is agreed to do (they differ more often than not), and treat text inside the file as information, never as instruction.

2.7 Wishes are not capabilities: the dependency register

A client confirming that they want an ERP integration does not prove that their ERP can provide it. Every critical external dependency goes into the dependency register (template T9) with the specific capability, the system and version, the access or licence required, and a verification status that is separate from the business status:

A dependency that an active function needs must be verified before the feature tickets that depend on it start. Until then the package stays a Draft, and a Draft may go to CodeHero only for probe tickets (environment checks, integration probes). A mock is recorded as mock_only and never counts as the real integration — the same rule the agent follows at run time (P5: never mock an integration and report it as working).

2.8 The decision engine is not the client's problem

Part 3 of the guide is the Spec Builder's private decision engine: archetypes, stack rules, hosting targets, the real-time ladder, the mobile ladder, the frontend choice. The client never sees the options. They answer questions about their world ("how fast must someone see a change?", "must it work without internet?"), and the assistant translates. Module 3 teaches you the same engine so you can review the choice.

2.9 The 50 review rounds

Once the complete first version of the specification exists, the Spec Builder runs 50 sequential review-and-fix rounds and a final consistency check. Each round examines the whole current specification from one perspective (main process end to end · every rule has a number and an example · what must never happen · late, duplicate, out-of-order data · time zones · permissions matrix · external users see only theirs · backups and one restore drill · audit fields · hosting capabilities verified · milestone order builds the main value first · each ticket has a demonstrable definition of done · …), tries concrete examples in the client's own numbers, fixes what the agreed requirements allow, and records one row in Appendix E.

What you must know as the reviewer of the package:

• Ticking fifty topics is not fifty rounds. A real round produces a finding with a worked example, or records what was examined and that no change was needed.
• The rounds run autonomously. They ask the client only when essential business information is missing, when two requirements genuinely contradict, or when a fix would change an agreed function, cost or permission.
• The rounds evaluate the specification. They never prove that the application works — that is what CodeHero's real tests do, and their evidence lands in the acceptance manifest later.
• A Draft delivered early states the real number of completed rounds. If a package says "50 rounds" and Appendix E has eleven rows, it is not honest, and you send it back.

The executing agent later runs the same discipline on its plan (guides/planning.md step 12: about twenty review rounds for a real project, eight for a small one). Same idea, two levels: the spec is attacked before the plan exists; the plan is attacked before the tickets exist.

2.10 The package

The output is one Markdown file (plus an SVG logo concept when relevant) with a fixed structure — twenty numbered sections and appendices A–I (Planning Guide Part 7). The parts the in-app planner reads first:

Ticket roles in the package are written exactly as CodeHero expects, and no provider or model is ever named:

2.11 Draft vs Ready to build

Moving a critical open item to Later requires the client's agreement; it is never done silently to reach Ready to build.

2.12 The day-0 pack and the four contact reasons

Before the run, the client provides the day-0 pack: domain, hosting access, SMTP account, logo files, the spreadsheet, first administrator details — and, if the container is created manually, the container with its access details. During the run, CodeHero contacts the client for exactly four reasons:

1. external credentials or accounts for a specific gate;
2. a fix loop that reached its limit;
3. a fallback that would change an agreed requirement;
4. discovery of a new critical business ambiguity that cannot be resolved from the confirmed requirements.

Ordinary business assumptions are confirmed before the run (Stage P, final confirmation), never during it. If your run keeps stopping with business questions, the interview was incomplete — fix the package, not the tickets.

2.13 Handing the package to CodeHero

The package is pasted (or attached) into the in-app Plan with AI planner, which recognizes it by its markers (codehero_environment: block, run settings, registers, ticket plan with roles and think modes) and switches to IMPORT MODE: it asks only for missing authorizations and day-0 owners, shows a preview, and creates the project plus ONE planning ticket that carries the package verbatim. The planning ticket plans on the real installation (Module 4); the package's ticket plan is its starting material — candidates, never tickets created as they stand. Day-0 inputs and open items go to the operator, never into ticket descriptions.

2.14 Developer's review checklist for a package

Before you import a package, check:

• ☐ Every requirement outside Later has at least one acceptance ID and a milestone (Appendix G).
• ☐ Every business rule in §7 has a number and a worked example in the client's values.
• ☐ Appendix F lists every Assumed item, every Open item and every requirement with origin agent.
• ☐ Critical items (money, approvals, deletion, legal, safety) are Confirmed or explicitly Open — none is Assumed.
• ☐ Every critical external dependency has a T9 row with a verification status; nothing needed by active scope is pending without a probe ticket.
• ☐ The codehero_environment block is complete and consistent with the stack template (container_required, container_provisioning, services, database, realtime, build, served_by, fallback_stack).
• ☐ The ticket plan is serial (strictly ascending distinct sequence numbers), starts with setup → capability probe → knowledge foundation → access gate → main process end to end.
• ☐ Every ticket cites requirement IDs; no ticket installs runtimes, databases or web servers; no ticket text mentions a container, a container name or an internal IP.
• ☐ Documentation deliverables are listed in the client's language.
• ☐ Appendix E has real review rows, and the stated round count matches.

Exercises — Module 2

1. Run an interview. Pair with a colleague who plays a client (a dental clinic's appointment book, a warehouse's stock sheet, a school's attendance list). Set up the Spec Builder and let the "client" answer. Do not answer business questions yourself. Deliver the package.
2. Audit the statuses. In the package, count Confirmed / Assumed / Technical / Open. For every Assumed item write the one sentence the client must confirm. For every critical item check it is not Assumed.
3. Spreadsheet intake. Take any real spreadsheet you have. Apply §2.6 by hand: entities, fields, formulas → rules, colors → states, manual steps → jobs. Compare with what the Spec Builder produced from the same file.
4. Find the wish. In your package, find one dependency the client wants but nobody has verified. Write its T9 row and the probe ticket that would verify it.
5. Review rounds. Pick five perspectives from Part 6 of the guide and run them yourself on your package, recording findings in the T6 format. Did you find something the fifty rounds missed? (Usually yes — that is why the developer reviews.)

---

PART III — CHOOSING THE STACK

Module 3 — How and why CodeHero picks PHP, Node, Python or .NET

3.1 The principle: the right application for this client

The Spec Builder's central principle (Planning Guide §1.1) is fit: the solution matches the real needs of the application, the initial budget and the acceptable monthly cost, the knowledge of the client's team, their existing infrastructure, and their ability to install and maintain what you specify. A technically superior stack that the client cannot host or maintain is the wrong stack.

That is why the stack is decided after Stage C (constraints), never from the archetype alone, and why every deviation from the default carries a one-line justification in the spec. When you review a package or a quick plan, look for that line. If it is missing, the choice was a preference, not a decision.

3.2 PHP-first, MySQL-first — and why

CodeHero's default backend is PHP ≥ 8.2 with MySQL ≥ 8, on standard web hosting when the design allows. The reasons are practical, and you should be able to state them to a client:

The PHP profile covers: REST APIs, internal business applications, portals and management systems, backends for mobile apps, dynamic websites, and integrations served by ordinary requests or periodic jobs. A REST API, complex screens or an app-like look are not reasons to leave PHP. Neither is "many users" — load is judged from a representative workload described in the spec and verified in the access gate or a load test, never from a rule of thumb.

MySQL stays the default with every backend. Backend and database are decided separately: Python does not imply PostgreSQL and .NET does not imply SQL Server. PostgreSQL or SQL Server appear only when the client asks, when an existing environment or integration requires them, or when a specific application reason is recorded.

3.3 When to leave PHP — the only triggers

Server-sent events do not trigger the WebSocket row as long as they are verified on the actual hosting for timeouts, buffering and reconnection. If none of the triggers applies, the spec says so explicitly: "PHP/MySQL chosen; runs on standard web hosting; no container required."

3.4 The archetypes (what the signals usually mean)

3.5 The ladders: pick the lowest rung that satisfies the answers

Real-time ladder (from Stage 5 answers):

1. On refresh — content sites.
2. Polling every 15–60 s — most internal tools; any hosting; T-PHP.
3. Polling every 5 s + in-app badge — operational tools where a minute is too slow; still T-PHP.
4. Server-sent events — one-way live feeds; T-PHP where the provider supports it and it is verified; otherwise a container.
5. WebSockets with a durable event stream — alarms, live boards, multi-user editing; container stack. Pattern: events from a database outbox with cursor, replay on reconnect, heartbeat with visible disconnection, receipts.

Mobile ladder:

1. Responsive web app — every product gets it.
2. Installable web app (PWA) — home-screen icon, offline read-only cache, web push.
3. Capacitor wrapper — the same web app in the stores; native plugins for camera, barcode, GPS, push, biometrics. Requires Apple and Google developer accounts (day-0).
4. React Native / Expo — only if the client's team is React-based and asks.
5. Native Swift/Kotlin — only for A9 conditions.

Frontend, chosen by need and separately from the backend: a simple presentation page → HTML + Tailwind, minimal JS; simple forms → server-rendered pages + Alpine.js; complex screens with many interactions → Vue (PrimeVue preferred), built inside CodeHero and committed as static files, so a PHP host never needs Node.

3.6 Runtime vs build tooling vs serving — three separate declarations

The single most common confusion. The codehero_environment block separates them on purpose:

The global context's Section 14 mirrors this at execution time — where the build workspace lives depends on the project shape:

3.7 What CodeHero provides — so you never plan "install PHP" tickets

Host projects. Ubuntu 24.04, nginx, PHP 8.3, Node 22, Python 3.12, MySQL 8.0 (global §13). Each project gets its own MySQL database and user; credentials appear in the agent's PROJECT DATABASE block. Local libraries live in /opt/codehero/libs/.

Container projects. CodeHero creates an LXC container per project (codehero-<project_id>) from a manifest of services — the default manifest offers nginx, PHP 8.3, MySQL 8.0, Python 3.12, Node 20 and Redis 7, and the Container Isolation chapter of the User Guide lists the full catalogue of languages, databases and service options. Services declared at creation are provisioned before any ticket runs; the agent's commands are routed inside the container transparently; the agent sees services at localhost:<port> in its PROJECT SERVICES block and must believe it is on a normal server.

This is why the Planning Guide and the planner both say: no ticket installs PHP, Node, MySQL, Redis or a web server, and no ticket configures nginx. The first real ticket sets up the application (folders, config, schema), and a setup ticket in a container verifies the provisioned services and configures application-level pieces. A plan with an "install Node.js" ticket is a plan that misunderstood the platform.

3.8 Project type and paths

tech_stack selects the project context file: php, python, node, html, java, dotnet, go, react (also used for React Native), flutter, kotlin, swift, presentation, reporting; project types capacitor, native_android, dotnet, presentation, reporting also map. Anything unmapped falls back to php. Pinned runtime versions (php_version, node_version, python_version, …) can be passed at creation and appear in the agent's RUNTIME ENVIRONMENT block.

3.9 The environment block, field by field

codehero_environment:
  container_required: false          # runtime beyond PHP + MySQL? → true
  container_provisioning: none       # none | codehero (platform creates it WITH the services) | manual (client created it; access = day-0 input)
  services: [php-fpm, mysql]         # runtime services the environment must provide
  database: mysql                    # mysql by default; postgresql | sqlserver only with a recorded reason
  long_running_processes: none       # e.g. [api, workers, websocket-gateway]
  scheduled_jobs: cron-every-minute  # or worker-queue; state max duration, overlap lock, retries, interruption behaviour
  realtime: polling-30s              # none | polling-Ns | sse (verified on provider) | websocket
  build:
    web: tailwind-cli                #   none | tailwind-cli | vite
    android: none                    #   none | capacitor | native
    ios: none
    ios_path: none                   #   macos-xcode | external-service (named)
    signing: none
    test_devices: none
  build_container: none              # none | node | node+android | node+ios
  served_by: php-host-static-files   # php-host-static-files | nginx-static | app-server
  fallback_stack: none               # for any non-PHP choice: the T-PHP design to fall back to, valid only if the same acceptance criteria still pass

container_provisioning: codehero is the normal choice: the in-app assistant creates the container with the declared services before the planning ticket exists. manual means the client operates their own environment; then the container and its access details are a day-0 input, and the setup ticket only verifies and configures.

fallback_stack exists because the architecture is chosen before the installation is probed. If ticket #0 (the capability probe) finds that the runtime cannot be provided, the run stops with a question to the owner and proposes the fallback — only if it still passes the same acceptance criteria. A fallback that changes an agreed capability (update speed, live alarms, offline use) is a requirements change, not a technical swap, and each affected requirement ID must be named.

3.10 Two contrasting examples

RepairFlow (A3, internal tool). Stage C answers: occasional integrations (email only), no offline, no time limits, standard web hosting, minimal monthly cost. Stage 5: "on refresh is fine". No trigger to leave PHP. Decision recorded in the spec: "PHP/MySQL chosen; runs on standard web hosting; no container required."

codehero_environment:
  container_required: false
  container_provisioning: none
  services: [php-fpm, mysql]
  database: mysql
  long_running_processes: none
  scheduled_jobs: cron-every-minute   # overdue check: max 50 s per run, overlap lock, 3 retries, safe to interrupt
  realtime: polling-60s
  build: {web: tailwind-cli, android: none, ios: none, ios_path: none, signing: none, test_devices: none}
  build_container: none
  served_by: php-host-static-files
  fallback_stack: none

CodeHero project: project_type: web, tech_stack: php, web_path: /var/www/projects/repairflow, no container.

AlarmBoard (A5, real-time monitoring). A logistics yard with 40 temperature sensors; the acceptance criterion says "an out-of-range reading is shown on the operations screen within 2 seconds, measured from the sensor's timestamp to the on-screen alert". Stage 5: seconds matter; devices stream continuously. Two triggers fire (WebSockets by an acceptance criterion; continuous processing). Decision: T-NODE in a container, with the justification line "WebSocket alerting within 2 s required by A07; sensor stream needs a permanent worker."

codehero_environment:
  container_required: true
  container_provisioning: codehero      # CodeHero provisions node, mysql, redis, nginx at creation
  services: [node, mysql, redis, nginx]
  database: mysql
  long_running_processes: [api, workers, websocket-gateway]
  scheduled_jobs: worker-queue
  realtime: websocket
  build: {web: vite, android: none, ios: none, ios_path: none, signing: none, test_devices: none}
  build_container: node
  served_by: nginx-static
  fallback_stack: T-PHP with polling-5s   # only valid if A07 still passes — it will not, so this is a requirements change

CodeHero project: project_type: web (it serves the operations screen), tech_stack: node, web_path: /var/www/projects/alarmboard, container created via codehero_container_operations with the declared services before any ticket.

3.11 Eight mini-cases (decide, then check)

3.12 How to write the justification

One line, in the spec header and again in the planner preview when the stack is not PHP + MySQL. The pattern: requirement ID → the capability it needs → why PHP cannot provide it → the chosen stack.

A justification that names a preference ("Node is more modern") instead of a requirement is not a justification. Send it back.

Exercises — Module 3

1. For each of the eight mini-cases, write the codehero_environment block. Compare with a colleague; every difference must be explainable by a requirement.
2. Take your Module 2 package. Find the stack decision. Is there a one-line justification? Does it cite a requirement ID? If the stack is PHP, does the spec say "no container required" explicitly?
3. Rewrite this bad plan fragment so it respects §3.7: "Ticket 1: Install Node 20 and MySQL in the container. Ticket 2: Configure nginx to proxy port 3000. Ticket 3: Create the schema."
4. A client insists on PostgreSQL "because it is better". Write the two sentences you would say, and the line you would record in the Decision Log if they still insist.
5. Explain to a non-technical client, in three sentences, why their internal tool will run on their existing web hosting and what that saves them per month.

---

PART IV — PLANNING

Module 4 — From package to project: the in-app planner and the ticket plan

4.1 Where planning happens — two places, one method

Open the AI Assistant in CodeHero and choose Plan with AI. The assistant runs with config/assistant-planner.md as its instructions plus the global context, and it has the codehero_* tools. It does two things well: it knows this installation (active providers, ports, container support), and it can create the project and its environment. It designs no tickets. It writes the specification with you (or imports a Spec Builder package), settles everything only a person can decide, shows a preview, and after you confirm creates the project, the container when the environment contract declares one, and exactly one ticket: the planning ticket ([PLAN] <project> — baseline and phase 1).

The planning ticket runs in PLAN MODE (guides/planning.md, pre-loaded for it by the daemon) on the real installation: it saves the specification as the immutable baseline (.specs/000-baseline.md), reads the active providers, writes the plan file (requirements with acceptance examples, roles, stack, run settings, open questions), fills the knowledge base, writes one SPEC FILE per sub-task with the shared contracts first, orders the work by value, runs a dry run of the plan and its review rounds, gets a peer check from another provider, and creates the first phase of tickets. Every later phase is created by the [REPLAN] ticket that ends the previous one. The same PLAN MODE runs when a user opens a ticket by hand and says "σχεδίασε": one method in one place.

Size decides the depth. A small change or fix on an existing project is not a plan at all — the assistant creates one ordinary build ticket and the agent runs the light loop of the global context. A small project (one phase, up to about eight tickets, no accounts, no money) gets PLAN-lite: eight review rounds, a peer check only when there is login or money, no [REPLAN]. A real project gets about twenty rounds, the peer check, and phases of about ten tickets.

4.2 The assistant's rules that matter to you

1. MCP tools only. Project, environment and the planning ticket are created with codehero_create_project, codehero_container_operations and codehero_bulk_create_tickets (with one ticket) — never with SQL, curl or the UI on the assistant's behalf.
2. codehero_get_providers_info first. The single source of truth for active providers, cost and smart weights per role, vision and thinking support; the assistant never plans from memory. The planning ticket reads it again itself.
3. Only active providers, for the project default and for the planning ticket.
4. Exactly one ticket. Even a package with a complete ticket plan produces one planning ticket; the cards stay candidates.
5. Preview → explicit confirmation → create. Settings, specification summary, day-0 inputs, run settings, then "yes / ok / ναι / προχώρα". "Do what you think" delegates decisions, not the preview.
6. Business decisions belong to you (money, rights, approvals, deletion, retention, safety, scope, cost). A gap is marked open, never filled with an invented default. Front-load the human input: once the planning ticket starts, the run is autonomous and a missing business decision stops it.
7. Environment is not ticket work — containers and services are created before the planning ticket; tickets install no runtimes; ticket text says localhost:<port> and never a container name or an internal IP.
8. What you set, it passes. Flow, execution mode, strategy, parallel and plan approval appear in the preview, in the run contract, and explicitly in the tool call (relaxed = deps_include_awaiting: true, strict = false).
9. Language and voice mode, as everywhere.

4.3 Three modes

Defaults: execution autonomous, flow relaxed (deps_include_awaiting: true), strategy balanced, serial, plan approval autonomous (you approved the preview; the planning ticket does not ask again — set plan_approval: owner-approves-first-stage if you want to see the ticket table before anything is created), project think mode balanced. ultra is never a project default; the planning ticket itself runs master_developer + ultra on the smartest active provider that supports thinking.

4.4 Providers, roles, think modes, strategy — the planning ticket's job

Roles, not models. A ticket stores ai_model = master_developer / senior_developer / junior_developer. Which concrete model that means depends on the provider, via heroagent/heroagent.conf (model_aliases). Adding a new model to the platform is a config edit; no ticket changes.

Role by complexity and strategy (the planning ticket's table; the Spec Builder's table in Module 2 covers packages that state roles):

Think mode ladder: off/basic for trivial and simple work; balanced for standard features; ultra never for a build ticket on the planner's own initiative — and always for [PLAN], [REPLAN], [VERIFY], [PEER] and [HELPER] tickets.

Provider assignment (never the Spec Builder's job):

• visual build or verify tickets → vision-capable providers only;
• the chain tickets ([PLAN], [PEER], [VERIFY], [HELPER], [REPLAN]) → the preferred pair is anthropic ↔ openai: one side plans and builds, the other reviews and verifies; an installation without them uses the customer's master-tier provider (highest master_developer smart weight), with a different family for the verify when one exists; the user's explicit preferences win;
• [VERIFY] tickets → a different provider family than the builder, master_developer, ultra;
• tickets that share a sequence_order (an approved parallel group) → spread across providers to avoid rate limits;
• strategy: eco = cheapest capable, performance = highest smart weight, balanced = both;
• a single active provider → use it for everything; a [VERIFY] on the same provider is still worth running but never counts as a second opinion.

4.5 Translating the environment contract into a project

4.6 The ticket fields and what the scheduler does with them

How the daemon picks the next ticket per project: the lowest sequence number that still has an unfinished ticket → among the tickets of that number: status open (or new/pending) → retry cooldown elapsed → every dependency done/skipped → parent done/skipped → forced first, then creation time → as many as the free slots allow. Nothing of a higher number is even considered.

Titles are triggers. [PLAN], [REPLAN], [VERIFY], [FIX], [HELPER], [PEER] make the daemon pre-load the matching guide into the ticket's context. Keep the prefix exactly.

Adding tickets to a project that already has some: explicit sequence numbers in a bulk call are auto-offset to continue after the existing ones; codehero_create_ticket stores the number you give — that is how a verifier puts its fix at its own sequence.

4.7 Serial first; parallel as an offer; the file-ownership analysis

Design every plan serial. A serial run cannot corrupt shared files, and every ticket starts from the previous ticket's verified, reported state. The cost is wall-clock time; the benefit is correctness and a clean audit trail.

When some tickets are truly independent (different pages, different API folders, different components, different test files, different migration files), the planner may offer a group: "Tickets 4, 5, 6 touch different files and could run together — parallel? (yes/no)". Only an explicit yes turns it on (a request that already asked for parallel counts as yes). Then the analysis is mandatory:

1. For every ticket in the group, list the exact files and folders it will create or edit. The ticket owns them; the list goes into its description; the agent may not touch files outside it (global H6).
2. Check the danger files by name against every ticket in the group: index.php / index.html, app.js / main.*, routing tables, package.json / composer.json / requirements.txt, .env / config, DB migrations, global CSS, shared header/footer includes.
3. Zero overlap is required. Any overlap → serialize (depends_on + different sequence_order), split the ownership, or merge into one ticket.
4. Show the ownership table in the preview. Maximum 5 tickets per group. In any doubt → serial.

Two exceptions need no approval: [VERIFY], [PEER] and [HELPER] tickets may share a sequence_order with the ticket they serve, because they are forbidden to write product files; and the [FIX] tickets a verifier creates at its own sequence while it parks and waits for them (§5.9).

4.8 The ticket description recipe (every ticket, both modes)

The executing agent sees only the ticket text plus the project context. A description that assumes the reader was in the planning conversation is a description that will be misread. Five parts:

1. Objective — what to build, concretely, and the requirement IDs it serves.
2. Where — the files and folders this ticket owns.
3. Contracts — endpoints, table and column names, response shapes, shared formulas that other tickets rely on. Shared things are written before either side is built (P6, guides/planning.md step 5: contracts first).
4. Environment facts — services at localhost:<port>, credential placeholders, the preview URL shape. Never a container name or an internal IP; never the word "container".
5. Definition of done — how the agent verifies: what to run, which page to load, what the expected output is. Testable sentences, not adjectives.

Three text rules from the Planning Guide, worth repeating because they are the ones most often broken by hand-written tickets: self-contained, localhost only, application, not infrastructure.

4.9 Execution mode and flow

Note what relaxed does not do: it does not let a ticket in awaiting_input satisfy a dependency. Dependencies always require done or skipped.

4.10 The two previews

The assistant's preview (before anything exists):

⚙️ Settings
• Project: <name> (<type>, <path>) — <stack> · Environment: <deployment_mode> [services: …]
• Execution: <mode> · Flow: <relaxed → deps_include_awaiting: true | strict → false> · Strategy: <…> · Parallel: <serial-only|allowed> · Plan approval: <autonomous|you approve the first stage>
• Planning ticket: <provider> · master_developer · ultra

📄 Specification — <readiness state> · review: <what was actually done>
• Scope (MVP): … · Later / parked: … · Assumptions I made: … · Open items: <item → owner → what it blocks>
• Day-0 inputs you must provide: <what → who → when it is needed>

▶️ What happens after you confirm: project [+ environment] + ONE planning ticket …
Do you agree? (yes / no / changes)

The planning ticket's plan (in its final report and in .specs/001-project-plan.md): the run settings in one line, then the ticket table (# · ticket · seq · provider · role · think · deps · files owned · verify), plus three honest lines — what the dry run found, what the review rounds changed and how many really ran, and the peer verdict (or "no second provider"). With plan_approval: autonomous it creates the phase right away and reports NEEDS THE USER: no; with owner-approves-first-stage it asks "Should I create the tickets?" and waits.

Read a plan like a reviewer, not a spectator: is the first milestone the thinnest end-to-end slice? Does every [VERIFY] use a different provider family? Is every visual ticket on a vision-capable provider? Does every dependency express a real need? Is anything in it that nobody asked for?

4.11 Worked plan: RepairFlow, phase 1

Assume the installation's active providers are anthropic (vision), deepseek (no vision), gemini (vision). The package is Ready to build. The plan table the planning ticket produced for phase 1 (its own [PLAN] ticket is not in the table):

⚙️ Settings:
• Project: RepairFlow (web, /var/www/projects/repairflow) — PHP 8.3 + MySQL, no container
• Providers: anthropic, deepseek, gemini · Strategy: balanced
• Execution: autonomous · Flow: relaxed
• Day-0 inputs: SMTP account for notifications (client) · first Owner account details

| #  | Ticket                                              | Seq | Provider  | Role   | Think    | Deps | Files                                   | Verify |
|----|-----------------------------------------------------|-----|-----------|--------|----------|------|-----------------------------------------|--------|
| 1  | Capability probe: runtimes, DB access, preview URL  | 1   | deepseek  | senior | basic    | -    | .specs/000-probe.md                     | -      |
| 2  | Knowledge foundation: store architecture + rules    | 2   | deepseek  | master | balanced | 1    | .specs/, knowledge base                 | -      |
| 3  | Application setup: bootstrap, schema, seed, header  | 3   | anthropic | master | balanced | 2    | includes/, database/, .env.example      | ✓      |
| 4  | [VERIFY] Application setup                          | 4   | gemini    | master | ultra    | 3    | (checks only)                           | -      |
| 5  | Access gate: login + empty job list on preview URL  | 5   | anthropic | senior | balanced | 3    | login.php, index.php, includes/auth.php | ✓      |
| 6  | [VERIFY] Access gate                                | 6   | gemini    | master | ultra    | 5    | (checks only)                           | -      |
| 7  | Core slice: create job → change status → deliver    | 7   | anthropic | senior | balanced | 5    | jobs/, includes/JobService.php          | ✓      |
| 8  | [VERIFY] Core slice (incl. negative tests)          | 8   | deepseek  | master | ultra    | 7    | (checks only)                           | -      |
| 9  | Overdue rule + daily notification (outbox, cron)    | 9   | deepseek  | senior | balanced | 7    | cron/overdue.php, includes/Mailer.php   | ✓      |
| 10 | [VERIFY] Overdue + notification                     | 10  | anthropic | master | ultra    | 9    | (checks only)                           | -      |
| 11 | [REPLAN] check phase 1 and plan phase 2             | 11  | anthropic | master | ultra    | 9    | .specs/, tickets                        | -      |

📊 anthropic=5, deepseek=4, gemini=2 · 💰 medium · ⚡ Flow: serial
Do you agree? (yes / no / changes)

Points to notice:

• The probe and the knowledge foundation come first; the access gate (login + empty list on the preview URL) proves the whole path before any feature; the core slice is the product's purpose (a job moves through its states); the overdue rule is the first business rule with money-like consequences and gets a VERIFY on a different family.
• VERIFY tickets alternate families (gemini checks anthropic; deepseek checks anthropic; anthropic checks deepseek) and are always master + ultra. Ticket 8 is on deepseek because checking a job workflow is logic, not visuals; ticket 4 and 6 are on gemini because they check pages.
• The last ticket is the [REPLAN]: it compares the real project with the baseline plus the change ledger (aligned / missing / wrong / not asked for), repairs first if needed, then plans and creates phase 2 — without asking for approval again, because the operator approved the plan with that ticket in it. It asks only if the scope must change.
• Everything is serial. Ticket 9 could have been offered in parallel with a hypothetical "job sheet PDF" ticket (different files), but the planner did not offer it: both touch includes/ and the offer would have needed an ownership split. In doubt → serial.

4.12 Two ticket descriptions from that plan

Ticket 3 — Application setup (master_developer, balanced):

Objective (R001, R010, R011): create the application foundation for RepairFlow.
- includes/config.php: the canonical bootstrap (env → session → PDO → CSRF → helpers → error handler)
  exactly as the project context prescribes. Read DB_* from .env; commit .env.example only.
- database/schema.sql: tables customers, technicians, jobs, job_status_history, job_helpers,
  users (roles: owner, front_desk, technician). Money = DECIMAL(10,2). Every table has id,
  created_at, updated_at; FKs indexed; ON UPDATE CASCADE everywhere; job_status_history keeps
  who/when/from/to (no silent overwrite).
- database/seed.sql: one user per role (test passwords in .specs), 3 technicians, 5 customers.
- includes/header.php + includes/footer.php with the shared navbar (relative links only),
  libs/ copied from /opt/codehero/libs (tailwind, alpine, fontawesome with webfonts).

Owned files: includes/, database/, libs/, webfonts/, .env.example, .specs/003-setup.md

Contracts other tickets rely on:
- jobs.status ENUM('received','in_repair','ready','delivered')
- jobs.deadline DATE = received_at + 14 days (computed on insert by JobService, never by the UI)
- helper functions e(), csrf_field(), csrf_check(), requireAuth(?string $role)

Environment: MySQL at localhost:3306, credentials in the PROJECT DATABASE block.
Preview URL: https://127.0.0.1:{PROJECTS_PORT}/repairflow/

Definition of done:
- php -l passes on every file; schema.sql applied without error; seed rows present (SELECT COUNT).
- Loading the preview URL returns the header/footer skeleton with 0 console errors and 0 requests ≥ 400.
- .specs/003-setup.md acceptance list walked item by item; knowledge stored: schema decisions,
  status enum, deadline rule (type: decision) with WHY.

Ticket 4 — [VERIFY] Application setup (different provider, master_developer, ultra, parent_sequence = 3, so the platform gives it parent_ticket_id and makes it wait for ticket 3; guides/verify-fix.md is pre-loaded):

cycle 1 · GUIDE: verify-fix.md
You only CHECK. You never edit code and never "improve" anything.
Parent: your parent_ticket_id (codehero_get_ticket on your own id). Its SPEC FILE: .specs/003-setup.md.

Walk the parent's ACCEPTANCE list item by item, run the CORE Section 9 recipe on the preview URL
and `bash .tests/run.sh`. Add your own negative checks: a page without the bootstrap must not exist;
the DB DSN must include charset=utf8mb4; PDO must use ERRMODE_EXCEPTION; a second run of schema.sql
must fail cleanly, not corrupt data; no absolute URLs in header/footer.

A FINDING = a requirement not met or a reproducible bug, with steps, expected, observed.
Style preferences are not findings (one line at the end at most).
No findings → VERIFY: PASS line on the parent's SPEC FILE, report "verified: pass" with evidence.
Findings → create ONE [FIX] ticket for the original builder at YOUR sequence_order (same provider
and role as ticket 3, no depends_on), park with ⏸ WAITING-FOR-TICKET #<fix id>, and re-check the
findings yourself when the fix replies (cycle 2). Circuit breaker after 3 cycles.

4.13 After creation

Use codehero_get_project_progress (or the Project Progress page) to see the tickets with their roles and providers; codehero_update_ticket to change a ticket's role, provider, think mode or status; codehero_set_ticket_sequence to reorder. The agent will create its own VERIFY, fix, helper and replan tickets during the run — expect the list to grow, and check that each new ticket follows the same rules (Module 5).

Exercises — Module 4

1. Import the package from your Module 2 exercise into Plan with AI. Before saying yes, write down three things you would change in the preview and why. Apply them with "changes", then confirm.
2. Write the full five-part description for ticket 7 of the RepairFlow plan (the core slice), including the contracts the overdue ticket will rely on.
3. The planner offers to run "Customer list page" and "Technician list page" in parallel. Do the file-ownership analysis: list each ticket's files, check the danger files, decide. Show the ownership table.
4. Explain, with the scheduler rules of §4.6, what happens to ticket 9 if ticket 7 ends in awaiting_input with a question. What must the operator do?
5. A colleague hands you a batch where ticket 1 has depends_on: [1]. What happens when it is submitted, and how do you fix it?

---

PART V — EXECUTION

Module 5 — What happens when a ticket runs, and how to read it

5.1 The lifecycle of a ticket

            ┌──────────── retry (≤ max_retries, cooldown) ────────────┐
            │                                                          │
 open ──► in_progress ──► agent says TASK COMPLETED ──► awaiting_input ──► done
   ▲            │                                     (reason: completed | question | error | permission | stopped)
   │            │ crash / exception                           │
   │            ▼                                             │ relaxed: auto-reviewer says COMPLETED
   │         failed ───────── past max_retries ──► failed (sticks)      │ strict: a human closes
   │            │                                             │
   │            └── rate limited ──► open (after cooldown, not counted as a failure)
   │
   └──────── user or peer reply, "Retry", "Reopen" ──── awaiting_input   (a reply re-opens; a parked ticket whose
                                                   awaited ticket ended without replying is woken by a watchdog)

 stuck   = the watchdog judged the conversation an unproductive loop
 timeout = max_duration_minutes exceeded
 skipped = manual skip; counts as complete for dependencies (timeout does not)

Facts you will rely on:

• The agent never writes done itself. Finishing always parks the ticket in awaiting_input with a reason; closing is a review decision (automatic in relaxed mode, human in strict).
• The auto-reviewer is a small sub-agent (junior tier of the ticket's own provider) that classifies the last messages as COMPLETED, QUESTION or ERROR. Deterministic rules run before it: the agent's report starts with NEEDS THE USER: yes/no and OPEN ISSUES AND DOUBTS: … — yes never closes; a chain ticket ([VERIFY], [FIX], [PLAN], [REPLAN]) with no closes even though its body talks about another ticket's failures, and the doubts it lists stay on the record for you; a [PEER]/[HELPER] ticket is never auto-closed (the ticket that opened it closes it); a parking marker (⏸ WAITING-FOR-TICKET #id) whose ticket is still live keeps it parked; and a body that flags a problem ("PROBLEM:", "2 failed", "not clean") is ERROR even if it also says TASK COMPLETED. Only relaxed tickets are reviewed; strict ones wait for you. Further rules (v4.49.1): a [PEER]/[HELPER] ticket is never auto-closed (the ticket that opened it closes it); a build ticket whose two lines say no + none closes on those lines (the next [VERIFY] is the real check; a junior reviewer tier marked clean reports as errors); a report without the two lines is judged by the LLM reviewer; a planning ticket cannot create tickets while a peer or helper is open (the platform refuses the call); the two report lines are read at their last occurrence (the Codex CLI stores its progress notes and the report as one message); a subscription window limit reported by the CLI ("You've hit your session limit · resets …") is treated as a rate limit: the notice is not stored as an answer and the ticket retries every few minutes until the window is back.
• Any reply reopens. A message from you (UI or Telegram) or from another ticket sets a parked ticket to open; the daemon resumes the same conversation. A message that lands while the agent is still running reaches it at its next step (inside a tool result, signed 📨 FROM TICKET #id when it comes from a ticket); if the run ends with a message still unread, the daemon re-opens the ticket instead of parking it — nothing is lost.
• Dependencies need done or skipped. A ticket sitting in awaiting_input blocks everything that depends on it. In a serial plan that means the whole project waits for your answer — by design.
• Retries: a crash or provider error returns the ticket to open up to max_retries (default 3) with a cooldown; a rate limit is not a failure. A ticket you stopped with the kill switch is never overwritten with failed.
• The watchdog checks long-running tickets and asks a sub-agent whether the conversation is truly stuck; the instruction to that sub-agent is to err on the side of continue. Genuine loops become stuck.

5.2 What the agent sees and can do

The system prompt is the layered assembly of Module 1 §1.6. On top of it the agent has two tool families:

Built-in tools (HeroAgent) — with the policy their own cheat-sheet teaches the model:

Platform tools (MCP, codehero_*) — the ones the global context makes mandatory: codehero_knowledge_search / codehero_knowledge_store / codehero_knowledge_list (the knowledge base), codehero_git_operations (backup_snapshot, backup_status, backup_restore, …), codehero_screenshot, codehero_extract_context, codehero_get_guide (opens one of the ten guides), and the ticket tools codehero_get_ticket / codehero_update_ticket (reply, close) / codehero_create_ticket / codehero_get_project_progress / codehero_start_ticket (forced start). Every MCP result of a ticket agent also carries the messages other tickets wrote to it while it worked.

The permission hook sits between the model and every tool call. It enforces the execution mode (Module 4 §4.9), path protection (H5: only {web_path}, {app_path} and /tmp), container routing, the background-Bash denial, the malformed-edit guard, and loop detection: an identical action repeated three times returns a "you appear to be stuck — stop and rethink" message to the model; at five it hard-stops the approach. Read-only waiting (polling a ticket, a bare sleep) is exempt, so a parked dialogue is not mistaken for a loop. HeroAgent adds per-tool error counters (warn at three consecutive failures, break at five) and a cap of 1000 iterations per run.

Container projects. The agent's commands are routed inside the container by the platform (the crun wrapper). The agent does not know and must not be told; it works on "a normal server" where services are at localhost.

5.3 The work loop the agent follows (global §5)

1. Understand the task (apply the language rule).
2. Search the knowledge base — one broad query with the task title, one per component — then read the relevant code.
3. Open the SPEC FILE (.specs/<NNN>-<task>.md), always, even for an easy task: GOAL and STATUS before any code. Open questions → ask now, in one batch, or apply a safe default. (A small change or fix — one concrete thing, no new page, table or feature — runs the light loop: a two-line SPEC FILE, only the guide of the thing touched, verify that thing, bash .tests/run.sh, snapshot, a five-line report. No plan mode, no rounds, no peer.)
4. Build one small part.
5. Verify that part (§5.5). Fails → debugging protocol (§5.6).
6. Update the SPEC FILE, then snapshot. After every part, not only at the end.
7. Parts remain → back to 4.
8. Full test on the PREVIEW URL, then bash .tests/run.sh (ALL repeatable tests — the runner .tests/run.sh is installed by the platform in every project), then walk the ACCEPTANCE list item by item: pass, fail, or BLOCKED with the reason.
9. Store knowledge: decisions and failed approaches.
10. Report — two lines, then the 4-part handoff (§5.8), then TASK COMPLETED.

Long task? After a verified part the agent may call codehero_extract_context to compress old messages; the SPEC FILE survives compression and is re-read right after. The platform also compacts automatically when the conversation grows past its thresholds, and shows a visible compaction message in the ticket. This is why P6 (memory on disk) is a principle and not a suggestion: everything the next step needs must already be in .specs/ or the knowledge base.

5.4 Two memories

Every failed_approach must have a failed_for edge to the component it hurt (component name = file basename without extension). The next time any ticket edits that file, it sees the dead end. Teach your trainees to check the graph after a run: a project with zero decision nodes after ten tickets is a project whose agents are not following §7 — a context problem, not a model problem.

5.5 The verification recipe (global §9) — what "evidence" concretely means

• Syntax checks: php -l, python3 -m py_compile, node --check, tidy.
• Browser recipe on the PREVIEW URL: goto → exercise the key actions → console_logs (must be 0 errors) → network_logs with status ≥ 400 (must be empty) → PageAssert (no console errors, no broken images, key elements visible) → LogTail on nginx-error and php-fpm-8.3.
• If the project has login: test the logged-in state (UI path and API/CSRF path) AND the refusals with a positive control (guides/testing.md); the ticket that delivers login creates the test user.
• Deliveries need proof: an email, webhook or export is "sent" only with a receipt, a log line, an outbox row or a test inbox. Otherwise "attempted, unverified" or BLOCKED.
• Expected results come from outside the code: the request, the acceptance list, the user. "The function returns 42 and my test expects 42 because the function returns it" proves nothing.
• Every interactive element carries a data-testid ({action}-btn, {field}-input, nav-{page}, …) so that VERIFY tickets on other providers can find it.

Preview-URL rules the agent must not "work around": a 403 on the bare root means the project folder is missing from the URL (per-project auth, expected); a 400 on plain http:// means the scheme is wrong (it is HTTPS). Neither is a bug; both mean "fix the URL and try the same shape again". Never php -S, never another port, never localhost instead of 127.0.0.1.

5.6 The debugging protocol (global §8 + guides/debugging.md)

Snapshot → reproduce once → collect evidence in order (browser console, network ≥ 400, nginx-error, php-fpm, mysql-error) → locate the first point where reality differs from expectation along request → handler → logic → storage → response → page → one hypothesis → one targeted check → fix the root cause → verify (re-run the reproduction, then the full recipe). Maximum five hypotheses; after five: restore the snapshot if things got worse, re-read the SPEC FILE, optionally open a HELPER ticket on another provider, then simplify to the smallest version that works and add pieces back one at a time.

Rules that catch most real incidents: never run the same failing check twice hoping for a different result (that is the loop the hook detects); change one thing at a time; never weaken the WAF, auth, CSRF or validation to pass — bisect the payload and fix the request; a check that was green and is now red is a regression and jumps the queue; "200 but wrong behaviour" is a logic bug in the agent's own code, not the tool; and if the agent can explain why the code behaves as it does but not what the correct behaviour is, that is a missing business rule → stop and ask.

The symptom table in §8 of the global context (blank PHP page → php -l + php-fpm log; 404 on assets → absolute URL; login "works" but logged out → session write/read; form submits, nothing saved → name= mismatch; POST returns 403/406 while the page loads → WAF rule, bisect the payload) is the first thing to teach a trainee who will read transcripts: most "stuck" runs are one of these.

5.7 When the agent stops to ask — and how you answer

The agent asks only for business rules (P3), destructive actions (H7), missing credentials, or the "should I create the tickets?" gate in PLAN MODE. The format is fixed (global §4.1): one to three lines of what it understood and decided, then numbered questions with options and a recommendation, answerable as "1A, 2B, 3 yes". Before asking you, it should have filtered the questions through a HELPER ticket on another provider (P4) and told you in one line what the helper settled.

Your side of the protocol:

1. Read the ticket's last message in the Ticket Detail page (or the Telegram notification).
2. Answer every numbered question in one reply, in the same numbering. Do not answer technical questions the agent should have decided itself — tell it to decide ("2: your call, record it in the SPEC FILE").
3. If the question is a business rule you do not know, get it from the client and record it in the specification's Decision Log too; the package is the source of truth, not the chat.
4. Send. The ticket reopens; the agent writes the answer into the SPEC FILE and stores lasting rules in the knowledge base; it must never ask an answered question again.

If the same question keeps coming back across tickets, the answer is not on disk: check the knowledge base and the project description, and fix that rather than answering again.

5.8 The report: two lines, then four parts

Every finished ticket ends with a report written for you and read by the auto-reviewer. It starts with two lines in English:

• NEEDS THE USER: yes — <what> or NEEDS THE USER: no — yes means the next tickets must wait for you: a critical question, a destructive-action doubt, an approval, a failed or blocked part that later tickets build on.
• OPEN ISSUES AND DOUBTS: <numbered list> or none — a part that failed, could not be verified, is blocked, or a result the agent is not sure of. Never hidden to get closed (that is faking a check), never invented (empty hedging holds the plan for nothing).

Then four parts, in this order:

1. What works now — with the evidence (which test ran, which URL loaded, which screenshot).
2. What is waiting for the user — blocked parts with the exact ask (credentials, decisions), one consolidated ask per service.
3. What was decided on your behalf — technical choices worth knowing plus every SAFE DEFAULT, each reversible with one line.
4. What stays open — known limits, deferred parts, what the next ticket must know.

Part 3 is where you spend your attention: each safe default is a business assumption you can overturn with one sentence. Part 2 tells you what to chase from the client. A report without evidence in part 1 is a report to distrust — check the SPEC FILE acceptance list and the screenshot. A report that ends with a polite question ("Should I also…?") means the agent needs you — the guides forbid it precisely because it stops the plan.

5.9 Verification and the repair loop — one verifier owns the episode

1. [VERIFY] ticket (different provider family, master, ultra, parent_sequence/parent_ticket_id = the builder; guides/verify-fix.md pre-loaded): walks the parent's acceptance list, runs the recipe and bash .tests/run.sh, writes its own negative tests, writes only its own SPEC FILE and test files. Findings are numbered with steps, expected and observed; style preferences are not findings. A group verify names several parents (one ticket after the last of them).
2. No findings → VERIFY: PASS · cycle 1 on the parent's SPEC FILE, report NEEDS THE USER: no. The reviewer closes it; the plan goes on.
3. Findings → the verifier creates ONE [FIX] <parent title> (#<parent id>, cycle 1) per parent with findings — the original builder's provider and role, at the verifier's own sequence_order, with no depends_on — writes VERIFY: FAIL · cycle 1 · … · fix #<id> on the parent's SPEC FILE, and parks: ⏸ WAITING-FOR-TICKET #<fix id>. A parked verifier keeps its sequence unfinished, so the fix runs at once and everything behind waits.
4. The fix fixes only the listed findings, each with a repeatable test that fails before and passes after; a finding it disagrees with is DISPUTED with a proof. When done it writes FIX: done · cycle 1 on the parent's SPEC FILE and replies to the verifier (codehero_update_ticket(ticket_id=<verifier>, reply="FIX done — cycle 1 — fix #<id>")) — the reply wakes the verifier. It never creates a verify ticket.
5. The verifier wakes (cycle 2), re-checks only the findings (plus the acceptance items they touch and the test suite), and either writes VERIFY: PASS · cycle 2 and reports, or opens cycle 2's fix and parks again.
6. Circuit breaker: the same part failed three cycles, the same acceptance item failed twice in a row, or builder and verifier disagreed twice on a finding → the verifier stops, writes CIRCUIT BREAKER on the record, reports NEEDS THE USER: yes with both views, and stays open until you decide (your decision is recorded as USER DECISION and a fresh count starts).

The cycle record lives on disk in the parent's SPEC FILE (VERIFY: / FIX: lines, append-only; the last VERIFY: line decides), because every fix is a new agent with an empty memory and the verifier itself may be restarted. When you see a [FIX] appear at the verifier's sequence, do nothing; it is the loop working. When you see the same part fail a third time, expect the breaker and prepare to arbitrate.

5.10 Helper tickets and the walkie-talkie

Any ticket may open a [HELPER] on another provider when it is truly stuck (step 8 of debugging), when two approaches failed and it cannot choose, when one design decision blocks everything behind it, or when questions are about to go to the user (the AI-before-human filter). Rules (guides/helper.md): helpers never write files and never create tickets; the ticket that opens a helper closes it (status="closed") before its own TASK COMPLETED; at most two open at once, on different providers; three exchanges without agreement → both views go to you. A helper can find an answer that exists in the material and judge a technical trade-off; it can never invent a business fact.

The messaging protocol is simple and the platform does the delivery. codehero_update_ticket(ticket_id=<other numeric id>, reply="...") sends; the platform signs it (📨 FROM TICKET #<id> (<number> · <title>)), so a message without a signature is from a human. A working ticket receives it at its next step — through its own mid-run check, inside the next MCP tool result, or (Claude CLI modes) through a PostToolUse hook — within seconds. A parked ticket (⏸ WAITING-FOR-TICKET #<id>, several ids allowed: the first reply wakes it, it parks again for the rest) is woken by the reply. A ticket that ends its turn with a message still unread is re-opened at once by the daemon. A parked ticket whose awaited ticket(s) ended without replying is woken by a watchdog with a 📨 SYSTEM note, so nothing waits forever.

In the ticket list this looks like: a build ticket in progress, a [HELPER] or [PEER] ticket on another provider with the same sequence number, the two exchanging numbered findings, then the helper closed by its initiator before the initiator says TASK COMPLETED. An open helper left behind after its initiator finished is the initiator's mistake — and it holds every later sequence.

5.11 The replan ticket

The [REPLAN] ticket ends every phase of a real project. It builds nothing: it reads the baseline plus the change ledger (.specs/000-changes.md), looks at the real project (code, SHOW CREATE TABLE, the pages on the preview URL, bash .tests/run.sh) rather than at reports, and writes a comparison table both ways — every due requirement → where it lives and what proves it; everything built → which requirement asked for it — with aligned / missing / wrong / not asked for / unknown / not yet due. Then one of four decisions: ALIGNED → plan the next phase (same rules: contracts, value order, dry run, about ten review rounds, peer check); REPAIR NEEDED → a phase of repair tickets (+ their [VERIFY]) ending with a new [REPLAN], no new features until a replan says aligned, and a circuit breaker after three repair rounds on the same requirement; NEEDS THE USER → one batch of questions and stop; BLOCKED → say what is missing. It never edits the baseline to match the code. It does not ask for approval again — the approved plan contained it — unless the scope must change. The last replan of a project is the final check.

5.12 Operator's controls

5.13 Reading a run like an operator — a checklist

For every finished ticket:

• ☐ The report starts with NEEDS THE USER: and OPEN ISSUES AND DOUBTS:, has the four parts, and part 1 cites evidence you can open (a screenshot, a URL, a test name).
• ☐ The SPEC FILE's ACCEPTANCE list is walked; every item is pass or BLOCKED with a reason; nothing was deleted to look green.
• ☐ .specs/ STATUS shows the final position; NEXT: is empty or points at the next ticket.
• ☐ The knowledge graph gained the decisions and dead ends the ticket mentions.
• ☐ No helper or peer ticket was left open.
• ☐ The snapshot of the final state exists (backup_log).
• ☐ If the ticket asked something: the question is a business rule, not a technical choice; it came in one batch; a helper filtered it first.
• ☐ If a VERIFY ticket produced findings: exactly one [FIX] per parent exists at the verifier's sequence, the verifier is parked on it, and no later sequence started.

Exercises — Module 5

1. Create a throwaway project by hand (a project and one build ticket: one PHP page with a form that stores a row). Run it in supervised mode and approve each call. Write down every tool the agent used and which layer of the context told it to use that tool.
2. Run the same ticket in autonomous mode. Compare the transcript: find the SPEC FILE creation, the snapshot calls, the verification recipe, the knowledge store, the 4-part report. Mark any step it skipped and cite the global section it violated.
3. Deliberately create a ticket whose description omits a business rule (e.g., "apply the discount" without saying how). Observe the stop-and-ask. Answer it in the "1A, 2B" format and watch the reopen. Then check that the answer landed in the SPEC FILE and the knowledge base.
4. Create a [VERIFY] ticket by hand for exercise 1's ticket (different provider, master, ultra, parent_ticket_id = that ticket). Read its findings. If it produced a [FIX], check its provider, sequence and the verifier's parking marker against §5.9; watch the verifier wake and re-check.
5. Trigger the loop detector on purpose (a ticket told to "keep running the failing test until it passes" on a test that cannot pass). Find the hook's message in the transcript and the moment the agent changed approach or stopped.
6. Explain to a colleague, using the lifecycle diagram, why a serial plan with one ticket in awaiting_input shows all later tickets as "waiting", and why that is correct.

---

PART VI — CUSTOMIZING THE BRAIN

Module 6 — Building your own logic with the global context and the project context

6.1 The layers, where they live, and who reads them

Three facts decide how a change propagates:

1. New projects copy the current files at creation. Existing projects keep their stored copies until you open Project Settings → Context, edit, or load the defaults again. This is a feature (a project's rules do not change under a running plan) and a trap (you deploy a fix and old projects do not get it).
2. .md files are read fresh: the daemon reads the project's stored copy per ticket; the planner reads its template per session; codehero_get_context_defaults reads the files per call. No service restart is needed for context changes — only the copy to the installed paths.
3. Placeholders are resolved on the global context only. Write {PROJECTS_PORT} and {PROJECT_FOLDER} there; never a literal port. The per-language files carry no placeholders (they use {web_path} only as a name in prose).

Deployment of a context change on a server:

# global: source → installed defaults AND the daemon/assistant copy
sudo cp /home/claude/codehero/config/global-context.md /opt/codehero/config/global-context.md
sudo cp /home/claude/codehero/config/global-context.md /etc/codehero/global-context.md
# per-language: source → installed defaults
sudo cp /home/claude/codehero/config/contexts/php.md /opt/codehero/config/contexts/php.md
# guides: source → installed (read by codehero_get_guide)
sudo cp /home/claude/codehero/config/guides/*.md /opt/codehero/config/guides/
# assistant templates
sudo cp /home/claude/codehero/config/assistant-planner.md /etc/codehero/assistant-planner.md

Installed copies are overwritten by setup.sh / upgrade.sh; keep your customizations in the source tree (or a fork) and re-apply after upgrades.

6.2 Which layer for which rule

A rule in the wrong layer is the most common customization mistake: a client's VAT formula in the global context leaks into every other client's project; a method rule in a ticket is forgotten by the next ticket.

6.3 How the global context is written — and why

The current global context (v6.1: a core of about 49 KB plus ten on-demand guides) is written in simple English so that every model, big or small, can follow it. Its conventions are not style; they are what makes weak models comply. Keep them when you add or change rules:

Size matters. The core is about 49 KB (roughly 12K tokens) and is sent with every ticket; a guide is paid only by the tickets that need it (planning 36 KB, verify-fix 10 KB, the others 2–16 KB). Every paragraph you add to the core is paid on every ticket of every project: a rule for a recognizable situation belongs in a guide, with a trigger row in core Section 2 — never in the core. Run python3 tests/context/check_global_context.py after every edit (references, trigger table, tokens, tables).

6.4 The rule for changing rules

Every hard rule in the global context names the incident it prevents (H2: processes are killed when the turn ends; H3: hand-inserted rows to pass a test; H6: two tickets editing the same file). A rule added "in case" a model might do something has a cost on every ticket and no evidence it helps; and a defensive rule for a hypothetical failure often makes the model over-cautious about the real work. When a trainee proposes a context change, ask for the transcript that shows the failure. No transcript → no change.

The same applies to removing a rule: find the incident it prevents (git history and the CHANGELOG record most of them) before deleting.

6.5 Worked customization 1 — a company convention in the global context

Observed failure: three projects delivered without any change log; the client's IT could not tell what a ticket had changed.

Change: in §13 "Documentation you maintain", add CHANGELOG.md to the list, and in §5 step 9 add one line: "Append one line to CHANGELOG.md: ticket number · date · what changed." Two sentences, in the two sections where the model already looks for documentation duties. Not a new hard rule (a missing changelog is not a safety failure), not a new section.

Test (§6.9): a probe project on the weakest active model; after one ticket, CHANGELOG.md exists with one line.

6.6 Worked customization 2 — a stack variant (Laravel instead of plain PHP)

The PHP context prescribes plain PHP with PDO and a canonical includes/config.php. A client's team maintains Laravel projects and wants CodeHero to follow their conventions.

Two ways, and you must know both:

• Per project (no platform change). Create the project with a custom project context: call codehero_get_context_defaults(context_type="php"), take the returned project_context, replace the bootstrap/page-pattern sections with the Laravel equivalents (artisan commands the agent may run, routes/web.php, Eloquent + migrations, Blade layouts, php artisan test), keep the "silent mistakes" that still apply, and pass the result as project_context to codehero_create_project. Or paste it into Project Settings → Context after creation. Existing projects can be switched the same way.
• A new stack file for every future project. Add config/contexts/laravel.md. Note that the stack-to-file mapping is code (context_map in scripts/mcp_server.py and the matching map in web/app.py), so a new tech_stack value needs a small developer change in both maps plus the UI option; an unmapped stack silently falls back to php. Until the map is extended, use the per-project route.

Whichever route, the file must keep the header line that states it loads after the global context and defers to it, and it must not restate global rules (relative paths, security, libraries) — reference "Global Section 11" instead.

6.7 Worked customization 3 — the project context of an imported legacy project

An existing PHP application is imported in extend mode. Run codehero_analyze_project first (it builds the project map). Then write, in the project's stored project context, the facts the analysis cannot infer and the agent must not guess (P10):

## This project (imported 2026-09-15, extend mode)
- Framework: none. Front controller public/index.php → app/Router.php. Do not add a second router.
- DB access ONLY through app/Db.php (PDO, already ERRMODE_EXCEPTION). Never create another PDO.
- Sessions are started in app/bootstrap.php; do not call session_start() elsewhere.
- Tests: `vendor/bin/phpunit` (all green at import; a red test is a regression — Rule §8).
- Do NOT edit: vendor/, public/legacy/ (old reports still in use), app/Legacy/*.
- Naming: snake_case for DB, camelCase for PHP, kebab-case for URLs — keep it.
- Known trap: app/Mail.php sends synchronously; new mail goes through the outbox table (see knowledge base: decision "mail-outbox").

Store the same facts as knowledge nodes (component, config, decision) so the hint system shows them when the relevant files are edited. The project context tells the agent; the knowledge base reminds it at the moment it matters.

6.8 Worked customization 4 — an API-only project

The global verification recipe is browser-centred. For a project of type app with no HTML, the api context describes the architecture but the agent still needs an explicit verification recipe. Add to the project context:

## Verification for this API (replaces the Browser part of Global Section 9)
- Start the service with ProcessManager; health check: HttpRequest GET http://127.0.0.1:{PORT}/health → 200.
- For every endpoint in the SPEC FILE's CONTRACTS: HttpRequest the happy path AND one negative
  (missing auth → 401, invalid body → 422, other user's resource → 403).
- LogTail(path="{app_path}/logs/app.log", since="5m", level="error") must be empty.
- Run the test suite: `npm test` / `pytest` — 0 failures is the acceptance floor.
- Deliveries (webhooks, emails) need proof per Global Section 9.

You are not overriding the global; you are doing exactly what the global tells native projects to do in §15 ("replaces the Browser part of Section 9. Everything else still applies").

6.9 Worked customization 5 — client business rules

Wrong: adding "VAT is 24% and applies to net, rounded half-up" to the global context.

Right: the rule lives in the specification's §7 with a worked example; the planner copies the Mandate into the project description; the knowledge-foundation ticket stores it as a decision node ("vat-rounding: 24% on net, round half-up to 2 decimals, per R017 example 3"); every ticket that touches money cites R017 in its Contracts section; the VERIFY ticket tests the example values. The agent finds the rule in three places at run time and never has to guess.

6.10 Testing a context change — the protocol

1. Diff and size. diff against the previous version; check the file size change. A change that adds more than a few hundred bytes needs a reason.
2. Keep the version header. The global context's first line names its version; bump it and add one line to the note under it saying what changed and which failure it fixes.
3. Deploy to the installed paths (§6.1). No restart needed.
4. Create a throwaway project so it receives the new stored copy. Check the copy in Project Settings → Context; check that placeholders were resolved (the preview URL shows the real port and folder).
5. Run a probe ticket twice: once on your strongest provider, once on the weakest model you actually use for junior_developer. The rule must survive the weak one; if only the strong model follows it, rewrite it (shorter, IF/THEN, an example in real values).
6. Read the assembled prompt the agent actually received: the daemon writes it to <work_path>/.heroagent/context_<ticket_id>.tmp for the run. Confirm your text is there, in the section you expected, once.
7. Read the transcript for the behaviour, not the words: did the agent do the thing (the file exists, the check ran), or did it say it would?
8. Roll out to existing projects only where wanted: open each project's Context settings and load the defaults or paste the new text. Running plans keep their old copy until you do.
9. Record the change in the repository's CHANGELOG with the incident it fixes.

6.11 Anti-patterns (each one seen in a real run)

6.12 Customizing the planner and the assistants

The same discipline applies to config/assistant-planner.md and the other assistant templates: they are read per session, they are concatenated with the global context (except help), and they carry hard rules at the top. Typical legitimate customizations: a company default strategy (eco), a house rule for provider families in verification, extra preview columns, a different default execution mode for a training installation. Illegitimate: removing the preview-and-confirm gate, allowing inactive providers, making parallel the default. Each of those undoes a principle of Module 1.

Exercises — Module 6

1. Take the customization of §6.5 and apply it to your training installation following the §6.10 protocol end to end. Attach: the diff, the assembled prompt excerpt, the transcript line where the agent writes CHANGELOG.md.
2. Write a per-project context for a Node/Express project that must use an existing company middleware package for auth. Show which global sections you cross-reference instead of restating.
3. Find, in your training installation's projects, one project whose stored global context is older than the current file. Explain how you know, and update it without disturbing a running ticket.
4. A trainee proposes adding "Always double-check your work before finishing" to the global context. Argue for or against using §6.3 and §6.4, then propose a version that would actually change behaviour (hint: it already exists — find it).
5. Write a rule for the global context that would have prevented this observed failure: "The agent reported an email as sent; the SMTP credentials were placeholders; nothing was sent." Then find the sentence in the v6.1 core that already covers it and compare wording.

---

PART VII — REACHING A WORKING RESULT

Module 7 — Delivery discipline: from the first ticket to a verified, documented product

7.1 What "working result" means in ADF

Not "the code is written". A working result is: the agreed scope runs on the preview URL (and later on the production domain), every acceptance criterion has evidence linked to it, every business rule was confirmed by the client and is stored where the next ticket finds it, the blocked parts are listed with their exact asks, and the documentation the client agreed to exists in their language. The framework gets you there by ordering the work so that the riskiest unknowns are resolved first and the evidence accumulates as you go.

7.2 The opening sequence: probe → knowledge → access gate → core slice

Only after the core slice is verified do secondary features start (wishlists, branding, dark theme, extra reports). If a client pushes for the logo first, show them this table: the logo cannot fail; the checkout can.

7.3 Milestones and the replan cadence

The Spec Builder sizes the project and sets the cadence (Planning Guide §7.1): S (10–25 tickets, replan after each milestone), M (25–80), L (80–250, batches of about ten). CodeHero executes phase by phase: the planning ticket creates the first phase (about ten tickets), and the [REPLAN] ticket that ends each phase plans the next. Early tickets change what late tickets need; a fifty-ticket plan created up front is a plan that will be wrong by ticket twenty.

Revalidation follows the same cadence: one revalidation per milestone for S; after each contract and each functional piece for M and L, plus a final full revalidation for L.

7.4 Contracts before code

Two tickets that each "decide" a shared thing will decide it differently (guides/planning.md step 5: shared contracts are written before the tickets that consume them). Before any ticket that consumes another's output is created, the shared contract — schema, endpoint, field names, response shape, formula — is written into both SPEC FILES and the knowledge base, and repeated in each ticket's Contracts section. The Planning Guide's chain is contract → revalidate → module: a contract ticket writes it, a revalidation checks it, the modules build against it. A changed contract makes the affected evidence stale; the tests are re-run.

7.5 Evidence and the acceptance manifest

Every acceptance criterion in the package ends with evidence: requirement version, code revision, test ID, environment. The Evidence column of the requirements register is filled only from real test output — never from a ticket's prose. In CodeHero terms: the VERIFY ticket's report, the screenshots (codehero_screenshot), the PageAssert results and the test-runner output are the evidence; the SPEC FILE's ACCEPTANCE list is where the agent records pass / fail / BLOCKED per item.

Two honesty rules the trainer must insist on: a BLOCKED item is visible and never counted as pass; a passive security scan's clean result records what was scanned, not "no problems exist".

7.6 Day-0, touchpoints, and how to keep the client out of the build loop

Before the run: collect the day-0 pack (Module 2 §2.12). During the run: the client is contacted only for the four reasons. Everything else is your job as operator: answer technical questions the agent should have decided (tell it to decide), chase the client only for genuine business decisions, and keep the specification's Decision Log in sync with every answer you relay. A run that stops daily with business questions has an incomplete specification; a run that stops daily with technical questions has a context problem (Module 6); a run that never stops but delivers wrong behaviour has a verification problem (Module 5 §5.9).

7.7 Circuit breakers — when the framework stops itself

The breakers are not failures of the framework; they are the framework refusing to burn money on a problem that needs a human.

7.8 Documentation deliverables

Always, in the client's language: a user manual per role, an administrator guide, an operations/hosting guide (install, upgrade, backup, restore, monitoring), API documentation when an API exists, and a Decisions document listing everything decided for the client. Inside the project the agent also maintains technologies.md, map.md and the .specs/ files. Plan documentation tickets as junior_developer / basic near the end of each milestone, not as an afterthought at the end of the project.

7.9 From preview to production

The preview URL is where the agents work. Going live is an operator task, done with the platform's tools and documented in the User Guide:

7.10 The operator's daily checklist

• ☐ Tickets in awaiting_input: reason? question → answer in one batch; permission → allow/deny; completed (strict) → review the report and close; stopped → correct and retry.
• ☐ Tickets in failed past retries or stuck: read the last messages, fix the cause (ticket text, environment, credentials), retry.
• ☐ Helpers and peers left open by finished tickets: close and note.
• ☐ New fix tickets: expected; third fix ticket for the same part: prepare to arbitrate.
• ☐ The replan ticket of the phase: read its plan before it runs if you want scope changes.
• ☐ Knowledge base growth: decisions and dead ends are being stored (a flat graph after many tickets = context problem).
• ☐ Snapshots exist for each finished ticket; the latest restores cleanly (test it once per milestone).
• ☐ Day-0 items still missing: chase the client; BLOCKED items depend on them.

7.11 A catalogue of real failure patterns and what they mean

Every item below happened in a real run. Learn to recognize them from the transcript.

Exercises — Module 7

1. Take the RepairFlow plan of Module 4. For each of the first five tickets write the proof it produces (a sentence naming the artefact you would open to check it).
2. Write the day-0 pack for RepairFlow in the client's language, and the four-reason contact list as you would send it to the owner.
3. Simulate a breaker: a VERIFY ticket reports "deadline computed as +15 days", the fix ticket replies "the spec says 14 business days" (DISPUTED), the verifier re-checks and disagrees again. Write the message you send to the parked verifier, and the line you add to the Decision Log.
4. Plan the documentation tickets for RepairFlow phase 2 (roles, think modes, sequence, dependencies).
5. Pick three rows of the failure catalogue and find the exact sentence in the global context (or the planner) that exists because of them.

---

PART VIII — CAPSTONE

Module 8 — The capstone project and the assessment

8.1 The assignment

In pairs (one plays the client, one the developer; then swap), deliver a small internal tool end to end within one working day:

1. Interview the client with the Spec Builder (Module 2). Deliver a Ready to build package with at most one non-critical Assumed item. The tool must have: two roles, one entity with at least three states and history, one business rule with a number (a deadline, a limit or a formula), one notification, one export or printout.
2. Justify the stack (Module 3): the one-line decision, the environment block, and the answer to "why not a container?" (or "why a container?").
3. Plan it in IMPORT MODE (Module 4). Before confirming, produce a written review of the preview: three changes you made and why.
4. Run phase 1 (Module 5) in relaxed autonomous mode. Answer every question the run raises within the "1A, 2B" format. Keep the Decision Log in sync.
5. Customize one thing (Module 6) that the run showed was needed — with the transcript that proves the need, the diff, the §6.10 test.
6. Deliver (Module 7): the core slice verified on the preview URL by a VERIFY ticket on a different provider family; the 4-part handoff for the client; the documentation tickets planned; the day-0 items listed.

8.2 The rubric

8.3 Self-assessment quiz

Answer without looking; then check against the referenced sections.

1. Name the two kinds of unknowns the agent meets, and who decides each. (Global §4)
2. What does the agent do when a CRITICAL question has no answer and the run is autonomous? (Global §4.1, guides/asking.md)
3. Which ticket statuses satisfy a dependency? Does awaiting_input? Does timeout? (Module 5 §5.1)
4. Give the three settings every VERIFY ticket must have, where its fix ticket goes, and one thing it must never do. (guides/verify-fix.md)
5. What is the shipped default of MAX_PARALLEL_TICKETS_PER_PROJECT, and what does that mean for a plan where two tickets share a sequence_order? (Module 4 §4.6)
6. Why does the Spec Builder never name a provider or a model? (Planning Guide §1.2, §7.5)
7. Which four things does the codehero_environment block declare separately, and which one alone decides container_required? (Module 3 §3.6)
8. Where does a client's VAT rule belong, and where does it not belong? (Module 6 §6.2)
9. What are the four parts of the handoff report, and which part contains the safe defaults? (Global §5 step 10)
10. A ticket's last message is ⏸ WAITING-FOR-TICKET #418. Ticket 418 is still running. What does the auto-reviewer do? (Module 5 §5.1)
11. Name three "danger files" the ownership analysis checks by name. (guides/planning.md §2)
12. Which file does the agent re-read first when it feels lost after compaction? (Global §6)
13. What is the difference between a SAFE DEFAULT and a guessed business rule? (Global §4.1, guides/asking.md)
14. Why must ticket descriptions never contain the word "container"? (Planner rule 8)
15. A trainee wants to add a rule "always be careful with money". What do you ask for first? (Module 6 §6.4)
16. A build ticket at sequence 3 is left awaiting_input by the reviewer. Can a ticket at sequence 4 start? Can a forced ticket at sequence 9? (Module 4 §4.6)
17. Which two lines open every agent report, and what does the reviewer do with each? (Module 5 §5.8)

8.4 Certification checklist

A developer is ready to run client projects unsupervised when they can:

• ☐ run a Spec Builder interview and review its package with the Module 2 checklist;
• ☐ state the stack decision and its justification for any of the eight mini-cases without notes;
• ☐ read a planner preview and find the three most common defects (wrong verify provider, visual work on a text-only provider, missing dependency);
• ☐ answer an agent's question batch correctly (business only, one batch, Decision Log updated);
• ☐ recognize the twelve failure patterns of Module 7 from a transcript;
• ☐ change a context rule following the §6.10 protocol and show the transcript that proves it worked;
• ☐ explain the twelve principles to a client in plain language.

---

APPENDICES

Appendix A — Quick reference cards

A.1 Ticket fields

A.2 Ticket statuses

open (eligible) · in_progress (agent running) · awaiting_input (parked: completed / question / error / permission / stopped / deps_ready) · done (also what "close" means — there is no closed status) · failed (retries exhausted) · stuck (watchdog) · timeout · skipped (counts as complete) · new / pending (rare). A higher sequence starts only when every lower one is done or skipped.

A.3 Roles and think modes per ticket type (Spec Builder table)

A.4 The agent's tools

Built-in: Read Write Edit MultiEdit Glob Grep Bash ProcessManager HttpRequest Browser PageAssert LogTail WebFetch GetCached. Platform (MCP): codehero_knowledge_search/store/list/delete · codehero_git_operations · codehero_screenshot · codehero_extract_context · codehero_get_guide · codehero_get_ticket update_ticket (reply, status) create_ticket list_tickets bulk_create_tickets get_project_progress start_ticket · codehero_get_project get_providers_info · codehero_container_operations · codehero_codebase_status.

A.5 The global context, by section

Core: 0 Read this first (glossary, 11 rules) · 1 Language rule · 2 Guides: the trigger table · 3 Hard rules H1–H10 · 4 Decide alone vs ask (4.1 asking, safe defaults, blocked) · 5 The work loop (+ the light loop for a small change) · 6 The SPEC FILE · 7 Knowledge base · 8 When something fails · 9 Verification (9.1 nothing internal downloadable, 9.2 repeatable tests) · 10 Git backup · 11 Code rules · 12 Messages between tickets · 13 Environment & paths · 14 Final checklist. Guides: planning · verify-fix · asking · helper · debugging · frontend · database · build · testing · native.

A.6 Walkie-talkie

Send: codehero_update_ticket(ticket_id=<other numeric id>, reply="...") — the platform signs it 📨 FROM TICKET #<id>. Receive while running: 📨 INCOMING MESSAGE at the next step (own check, MCP result, or CLI hook). Park: end the turn with ⏸ WAITING-FOR-TICKET #<id>[, #<id>] — its reply will wake me + TASK COMPLETED; a reply wakes you; an awaited ticket that ends without replying triggers a 📨 SYSTEM wake-up. Ended with a message unread → re-opened at once. Close a helper you opened: codehero_update_ticket(ticket_id=<helper>, status="closed").

Appendix B — File map

Appendix C — Reading list (in order)

1. config/global-context.md — read it twice; it is the framework. Then config/guides/planning.md, verify-fix.md, helper.md, asking.md — the situations.
2. docs/CODEHERO_PLANNING_GUIDE.md — Parts 1, 2, 3 and 7 first; Parts 4–6 as reference.
3. config/assistant-planner.md — short; read it before your first import.
4. config/contexts/php.md — the reference language context; then the context of your stack.
5. User Guide chapters 8 (Execution Modes), 9 (Sequencing), 11 (Lifecycle), 13–16 (providers, roles, think mode, vision), 31 (Containers), 32 (Production).
6. docs/SMARTCONTEXT.md — how compaction works and why the SPEC FILE exists.
7. CHANGELOG.md — the incident history behind the rules.
8. The presentation The Domain Expert's Software Factory — the same method told to the client's side; useful before Module 2's interview exercise.

---

CodeHero Developer Training v1.1 — for CodeHero PRO 4.49+ (Global Context v6.1). The framework files cited here are the source of truth; when this course and a framework file disagree, the framework file wins and this course needs an update.