CodeHero Developer Training — The Autonomous Development Framework (ADF)

Version 1.10 · October 2026 · For CodeHero PRO 5.0.2 and later

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: ask up to three related business questions in one message, one for a difficult choice;
      │  reuse supplied answers and show a first picture early · 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  (VERIFY on another provider family; role + think per ticket kind, §4.4)
      │
      ▼
 END OF THE LINE  ([SECURITY] senior+pro and [PERFORMANCE], each with its [VERIFY] of the other family;
      │  the final [REPLAN]: docs/acceptance.md + docs/handover.md, restore drill on record, [VERIFY] final acceptance)
      │
      ▼
 HANDOFF REPORT → operator → client   (works+evidence · waiting on you · decided for you · open)

The end of the line (4.65.1–4.65.2). Think of a car plant: every station checks its own work, a different inspector signs each hand-over, and before the car leaves the line it passes the crash test and the dynamometer; then the pre-delivery inspection, the keys and the manual. In CodeHero the last phase holds the [SECURITY] test (two different senior models at pro, every class tested actively, locally by default) and the [PERFORMANCE] test (the server's own speed measured first, the specification's volume seeded), each re-run by a [VERIFY] of the other provider family; the final [REPLAN] writes docs/acceptance.md (every requirement with its evidence) and docs/handover.md (install, the first-administrator step, backups and the restore drill, upgrade, logs, help per role) in the customer's language, and a real project gets one [VERIFY] final acceptance that reads both against the real product. A [RELEASE] ticket delivers a candidate; the [REPLAN] behind it accepts it after the phase's full run. The ticket description is the station's work-instruction sheet: the planner writes into it everything the agent would otherwise have to search for.

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. Installed core instructions, loaded fresh on every run.
4. Installed stack sections selected by project_stack and the ticket role, loaded fresh on every run.
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 SEARCH TOOLS === — only when the Codebase Map and/or semantic search are on for the project: which tool answers which question (definitions and callers → the map; questions by meaning → semantic search; text → Grep).
9. === PROJECT SERVICES === — databases, caches and web apps with localhost:<port> and credentials ("already installed and running").
10. === PROJECT SECRETS === — the names (never the values) of the project's secrets and how to use them by path.
11. Container execution rules and the container app-deployment guide (container projects only).
12. 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>").

Three consequences you will use constantly:

• Since 4.66.2, the installed core and the stack sections selected by project_stack load on every run; they are never copied into a project. global_context, project_context and context contain only the user's explicitly requested additions, in the user's words. Do not put the core, a stack section, a guide, a template, an automatically generated project analysis or the specification in these fields. The specification belongs in the planning ticket.
• The fields reach agents only when additional_context_enabled is on. New projects start on; projects present at the 4.66.2 upgrade start off. Overrides apply above platform defaults, in order global < app < notes.
• Before clearing legacy content or enabling overrides, read the existing fields, distinguish installed copies from customer additions, show exactly what will change, and obtain the user's confirmation. clear_context_fields=true clears global and app context according to the tool schema; do not assume it preserves customer text or clears notes. Preserve confirmed customer additions. There is no refresh-global-context action. codehero_get_context_defaults is read-only; never copy its result into a project.

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 the list as a dated exercise record. Every actual plan and provider assignment refreshes codehero_get_providers_info; the exercise snapshot is not current authority.
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: ask up to three related business questions in one message, one for a difficult choice; reuse supplied answers and show a first picture early; 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?

Spec Builder 1.28 targets roughly 6–8 business decisions for a small scope, 12–18 for medium and 20–30 for large work. These are targets, not quotas or permission to leave a critical decision unresolved.

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.

Use three states, scoped to explicitly listed active requirement IDs:

• Draft for confirmation: unresolved confirmation, critical business decisions or essential feasibility; no dependent feature work authorized.
• Ready for scoped discovery: the user approved a bounded feasible probe, its cost, owner and expected evidence; list allowed probes and blocked features.
• Ready for active-scope construction: critical business decisions and necessary feasibility for that scope are settled, and first-step inputs are available; later inputs have owners and gates.

A Draft does not authorize a probe automatically. Confirm the discovery scope and the in-app preview first. A legacy Ready to build label is a claim to check, never an automatic conversion. Moving requirements to Later needs the user's agreement.

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 Review groups and the final check

Review the complete draft in groups sized to the specification: 2 for small, about 5 for medium and up to 10 for large, followed by the final consistency check. Cover each applicable perspective and exercise worked examples; log what was actually checked and changed. A draft delivered early states the groups actually completed. Do not claim runtime verification from this review.

PLAN MODE performs a separate review on the real installation, using its own size/pace rules. The Spec Builder's review neither replaces that review nor fixes its ticket count.

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:

Size first: a small existing change uses one ordinary build ticket, plus verification when provider restrictions require it. A simple new build (about three screens or fewer, one user type, no login, money, integration or personal data) uses one build and one other-family VERIFY. Larger work uses the approved specification and one PLAN ticket; only that ticket designs and creates the work phases.

A small plan has up to about five work tickets, two review groups, a closing VERIFY and REPLAN, and a peer for applicable risky work. A real plan uses up to ten review groups, a peer and phases of about ten tickets ending in REPLAN. Fast pace uses fewer groups; ultra-fast is an explicitly requested demo with disclosed omissions. Counts are limits or estimates, not quotas. Provider rollout restrictions apply at every pace.

PLAN, REPLAN, PEER, VERIFY and HELPER normally use senior_developer + balanced; a peer/helper is never weaker than its opener. pro is for a very critical core or the documented failure escalation. Work is junior_developer by difficulty: trivial off, very simple fast, simple basic, moderate balanced; hard work is senior + balanced. master_developer is only on explicit request. ultra is never a project default and is not an automatic chain-ticket setting.

FIX cycle 1 uses the builder's role and think mode; cycle 2 goes up one think step; cycle 3 uses senior + pro, never below the builder. Security episodes use senior + pro; performance episodes use senior + balanced, with the specified critical-SLA exception. Release work is senior_developer + balanced (GUIDE: release.md). The planning ticket applies the current guides, pace exceptions, eligibility and user choices.

These are candidates: the planning ticket re-sizes every card by its difficulty on the real installation (§4.4).

2.11 Draft vs Ready to build

Use three states, scoped to explicitly listed active requirement IDs:

• Draft for confirmation: unresolved confirmation, critical business decisions or essential feasibility; no dependent feature work authorized.
• Ready for scoped discovery: the user approved a bounded feasible probe, its cost, owner and expected evidence; list allowed probes and blocked features.
• Ready for active-scope construction: critical business decisions and necessary feasibility for that scope are settled, and first-step inputs are available; later inputs have owners and gates.

A Draft does not authorize a probe automatically. Confirm the discovery scope and the in-app preview first. A legacy Ready to build label is a claim to check, never an automatic conversion. Moving requirements to Later needs the user's agreement.

2.12 Inputs, owners and contact gates

List only inputs the agreed scope requires. Each row names item, owner, affected requirement IDs, needed-before step, status and closure evidence or reference; never a secret value. First-step inputs must be available for construction readiness. Later domain, SMTP, store, logo or import inputs wait at their explicit gates and do not block unrelated approved work.

Front-load known business decisions and batch questions. Contacts can also be required by scoped discovery/fallback, repair-loop escalation, owner-first-stage approval, strict flow, execution-mode permissions, new-service approval and exact destructive-operation consent. Autonomous execution does not remove these gates.

2.13 Handing the package to CodeHero

IMPORT recognizes environment_contract (and explicitly translated legacy codehero_environment), the run contract and registers. It preserves the source, validates active-scope readiness, previews the allowed route and waits for explicit approval before creating project/environment/tickets. 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. The planning ticket carries DAY-0 INPUTS AND OPEN ITEMS with item, owner, affected requirement IDs, needed-before step, blocked scope and closure evidence. Secret values stay out; the ticket names only the Secrets-panel/path reference and who supplies it.

2.14 Developer's review checklist for a package

Before you import a package, check:

• &#9744; Every requirement outside Later has at least one acceptance ID and a milestone (Appendix G).
• &#9744; Every business rule in §7 has a number and a worked example in the client's values.
• &#9744; Appendix F lists every Assumed item, every Open item and every requirement with origin agent.
• &#9744; Critical items (money, approvals, deletion, legal, safety) are Confirmed or explicitly Open — none is Assumed.
• &#9744; Every critical external dependency has a T9 row with a verification status; nothing needed by active scope is pending without a probe ticket.
• &#9744; Use the current environment_contract from CODEHERO_PLANNING_GUIDE.md §3.3. Preserve all runtime, service ownership, database, background/scheduled work, realtime, build/signing/device, serving, fallback, test and activation fields. Treat codehero_environment only as legacy import data, with an explicit translation and unknowns preserved.
• &#9744; The ticket plan is serial (strictly ascending distinct sequence numbers). PLAN records architecture and decisions in project knowledge itself. The first SETUP ticket checks capabilities and application/service readiness; create a separate discovery probe only when the approved scope actually requires one. Follow with the thinnest useful confirmed flow, not a fixed quota of foundation tickets.
• &#9744; Every ticket cites requirement IDs. Omit container names, internal container IPs and host-side entry commands from ticket instructions; retain the truthful environment contract and obey the supplied execution context. A container SETUP may close approved service gaps through GUIDE: services.md; host system installation remains an operator input.
• &#9744; Documentation deliverables are listed in the client's language.
• &#9744; 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 recorded review groups 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 no need justifies a different backend, choose PHP/MySQL. State the required hosting capabilities and their verification gate; do not claim a particular host is suitable or container-free until its capabilities are known.

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; use suitable verified existing hosting/native infrastructure, or an approved platform container when required capabilities are otherwise unavailable. Runtime needs, build tools and provisioning are separate decisions; preserve the user's constraints.
5. WebSockets with a durable event stream — alarms, live boards, multi-user editing; use suitable verified existing hosting/native infrastructure, or an approved platform container when required capabilities are otherwise unavailable. Runtime needs, build tools and provisioning are separate decisions; preserve the user's constraints. Pattern: events from a database outbox with cursor, replay on reconnect, heartbeat with visible disconnection, receipts.

Mobile ladder:

1. Responsive web app — products with human-facing web pages use responsive layouts; APIs, CLIs and native-only products do not gain a new web app by default.
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). Declare the required build tools and a verified build owner/environment separately from the runtime host. A deployment target serving prebuilt static assets need not run Node, but that is not proof that a suitable build environment already exists. The planning ticket chooses output paths and the platform packaging workflow.

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/.

Preserve the approved environment_contract in the specification. Ticket instructions describe the project's actual execution environment, project paths, local service ports and secret references; they omit container names, internal container IPs and host-side entry commands. Colocated services use localhost:<verified port>; external services keep their real endpoints. Browser checks use the platform preview URL.

After approval, create the project and its declared platform container and catalog environment through MCP before the planning ticket. nginx is built in and is never declared as an additional service. The planning ticket may discover an approved service gap: its SETUP ticket can install or register it inside the project container under GUIDE: services.md. Missing host runtimes are operator-owned inputs; tickets do not install them.

Destruction, migration, stopping the container, and restoring or deleting a snapshot require the user's explicit yes for the exact operation. For supported container actions, pass user_confirmed=true only after that yes. Never invent a network action or a parameter absent from the live schema.

3.8 Project type and paths

project_type controls the supported project/path category; project_stack explicitly selects installed stack sections. Valid stack choices are php, node, python, mysql, html, java, dotnet, go, react, react_native, capacitor, flutter, kotlin and swift. Do not pass capacitor, native-android or dotnet as invented project_type values, or use react as the React Native context. 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

environment_contract:
  deployment_mode: <standard-hosting|native-host|platform-container|existing-infrastructure>
  container_policy: <allowed|forbidden>
  initial_target: <confirmed target or owned open item>
  future_target: <confirmed target|none|owned open item>
  services:
    - {name: <required service>, runtime: <required runtime>, install_owner: <role>, lifecycle_owner: <role>}
  database: <required database|none>
  long_running_processes: <required processes|none>
  scheduled_jobs: <confirmed need, duration, overlap, retry and interruption rules|none>
  realtime_by_use_case: <requirement IDs, acceptable delays and evidence|{}>
  build: {web: <need|none>, android: <need|none>, ios: <need|none>, ios_path: <path/owner|none>, signing: <owner/reference|none>, test_devices: <devices/owner|none>}
  build_container: <required build environment|none>
  served_by: <runtime serving the deployed output>
  fallback_stack: <equivalent approved option|none>
  test_environment: isolated-local
  production_activation: separate-gate
# Container disk size (GB): <preview-confirmed requirement, or not applicable>
# Availability/evidence: <references to capability register rows; never inferred from this template>

Choose deployment_mode from the confirmed target, actual capabilities and user constraints; there is no language-driven default to platform-container. Existing manual infrastructure has a named operator and access gate. A missing host capability is an operator input; approved catalog/custom container gaps are closed by SETUP under GUIDE: services.md.

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."

environment_contract:
  deployment_mode: standard-hosting
  container_policy: allowed
  initial_target: <confirmed target; capabilities to be verified>
  future_target: <agreed target|none|owned open item>
  services:
    - {name: web, runtime: php, install_owner: host-operator, lifecycle_owner: host-operator}
    - {name: database, runtime: mysql, install_owner: host-operator, lifecycle_owner: host-operator}
  database: mysql
  long_running_processes: none
  scheduled_jobs: <only confirmed overdue/notification work; cadence, overlap, retries and interruption rules>
  realtime_by_use_case:
    job_status: {acceptable_delay: "visible when the user refreshes", transport: manual-refresh}
  build: {web: <needed and verified tool|none>, android: none, ios: none, ios_path: none, signing: none, test_devices: none}
  build_container: none
  served_by: php-host-static-files
  fallback_stack: none
  test_environment: isolated-local
  production_activation: separate-gate
# Host availability and the acceptable monthly cost still require their own evidence/decision.
# Do not turn a spreadsheet highlight into a scheduled email or an agreed hosting-only budget.

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."

environment_contract:
  deployment_mode: platform-container
  container_policy: allowed
  initial_target: codehero-host
  future_target: none
  services:
    - {name: application, runtime: node, install_owner: codehero, lifecycle_owner: codehero}
    - {name: database, runtime: mysql, install_owner: codehero, lifecycle_owner: codehero}
    - {name: cache, runtime: redis, install_owner: codehero, lifecycle_owner: codehero}
  database: mysql
  long_running_processes: [api, workers, websocket-gateway]
  scheduled_jobs: <worker-queue duration, overlap, retries and interruption behavior to be established>
  realtime_by_use_case:
    A07: {required_delay: "sensor timestamp to visible alert <= 2 seconds", transport: websocket, evidence: pending}
  build: {web: vite, android: none, ios: none, ios_path: none, signing: none, test_devices: none}
  build_container: <needed build tooling; availability not yet verified>
  served_by: nginx-static
  fallback_stack: none
  test_environment: isolated-local
  production_activation: separate-gate
# Example only: use these service choices and owners only if confirmed for this installation.
# nginx is built in, not an additional service. Container disk size is confirmed in the preview.
# Polling every 5 seconds cannot satisfy A07 and is not an equivalent fallback.
# Until the necessary feasibility is evidenced, this example is discovery scope, not construction-ready.

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). Size first: existing small changes and simple new builds use their explicit exceptions.

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 first: a small existing change uses one ordinary build ticket, plus verification when provider restrictions require it. A simple new build (about three screens or fewer, one user type, no login, money, integration or personal data) uses one build and one other-family VERIFY. Larger work uses the approved specification and one PLAN ticket; only that ticket designs and creates the work phases.

A small plan has up to about five work tickets, two review groups, a closing VERIFY and REPLAN, and a peer for applicable risky work. A real plan uses up to ten review groups, a peer and phases of about ten tickets ending in REPLAN. Fast pace uses fewer groups; ultra-fast is an explicitly requested demo with disclosed omissions. Counts are limits or estimates, not quotas. Provider rollout restrictions apply at every pace.

PLAN, REPLAN, PEER, VERIFY and HELPER normally use senior_developer + balanced; a peer/helper is never weaker than its opener. pro is for a very critical core or the documented failure escalation. Work is junior_developer by difficulty: trivial off, very simple fast, simple basic, moderate balanced; hard work is senior + balanced. master_developer is only on explicit request. ultra is never a project default and is not an automatic chain-ticket setting.

FIX cycle 1 uses the builder's role and think mode; cycle 2 goes up one think step; cycle 3 uses senior + pro, never below the builder. Security episodes use senior + pro; performance episodes use senior + balanced, with the specified critical-SLA exception. Release work is senior_developer + balanced (GUIDE: release.md). The planning ticket applies the current guides, pace exceptions, eligibility and user choices.

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, together with codehero_get_model_table (every model of every active provider, §4.4).
3. Only active providers, for the project default and for the planning ticket.
4. Size first: existing small changes and simple new builds use their explicit exceptions. Larger BUILD/IMPORT work creates one PLAN carrying the unchanged specification; candidate cards are not a native bulk plan.
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. Omit container names, internal container IPs and host-side entry commands from ticket instructions; retain the truthful environment contract and obey the supplied execution context. A container SETUP may close approved service gaps through GUIDE: services.md; host system installation remains an operator input.
8. Every run setting appears in the preview and top-level run contract. Only actual schema parameters are passed to tools: execution_mode and deps_include_awaiting are explicit on single/bulk ticket creation; strategy, pace, parallel, plan_approval and release_policy remain contract data.
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 the first stage's work tickets are created), release policy none (a serious project — installed or upgraded outside this server, or holding business data an upgrade must not lose — gets at-milestones: the assistant proposes it in the preview, and the planning ticket judges again when the contract leaves it out), project think mode balanced. ultra is never a project default; the planning ticket itself runs senior_developer (master_developer only when you ask) — balanced; pro only for a very critical core or documented failure escalation — preferably on anthropic or openai, otherwise on the strongest 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.

Models on merit (5.0.1). A provider usually offers more models than its three role defaults. codehero_get_model_table lists them all: provider · model · the roles that use it · vision · cost per 1M tokens · effective cost (a subscription counts 1/10) · score · the role the score earns · where the score comes from (our evaluation in model_ratings, or an estimate until a model is measured). The planning ticket may name a concrete model of the ticket's provider in the ticket's model field — the cheapest eligible model that meets the role, spread so every model works and gets measured; without it the role's default runs. The ticket's budgets (context window, output, compaction) follow the model that really runs. When one model fills two roles of a provider, the higher role thinks one step more by itself (never above pro; a ticket's own think mode wins).

Economy without losing quality. Spend where a mistake multiplies (the plan), save where the tokens go (the build tickets). On a real project of 35 tickets the build tickets used about two thirds of all tokens, verify about a tenth, plan + replan about a seventh, peers 2%. Most tokens are the context re-read at every step, not the thinking — so the model per build ticket and the number of steps matter most; think mode buys depth and costs speed.

Master only when you ask (it costs many tokens): two seniors of different families — the planner and its peer — reviewing it together, at most three exchanges, reach a good plan. You can override any role, on the project or on a single ticket.

Difficulty — judged by signals, never by feeling:

A part that failed before goes one step up; strategy eco one step down (never for Hard), performance one step up. The same role is not the same ability everywhere: read smart_weight in codehero_get_providers_info — Anthropic's junior (Sonnet 5, weight 9) may take moderate work, OpenAI's junior (gpt-6-luna, weight 7) only trivial and simple work.

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, senior_developer, balanced, basic for a trivial/simple parent, pro only for a very critical parent; apply live provider and ledger restrictions;
• 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;
• One active provider is usable only for work it is eligible and capable to perform. No-vision providers do not take visual work. In a change-ledger project, excluded roles cannot build/fix and verify-restricted roles need a validated other-family Anthropic/OpenAI verifier after their latest change. If that is unavailable, select an eligible validated builder or wait for the user's decision. Elsewhere, same-provider verification is labeled as such and is not an independent-family opinion.

4.5 Translating the environment contract into a project

4.6 The ticket fields and what the scheduler does with them

Ordinary scheduling considers the lowest unfinished sequence and starts open tickets whose dependencies and parent are done/skipped, subject to configured slots. Higher ordinary sequences wait until all lower tickets are done/skipped. Explicit forced start is a separate exception: it ignores sequence, dependencies, parent and slot limits and keeps its flag until cleared.

Titles are triggers. [PLAN], [REPLAN], [VERIFY], [FIX], [HELPER], [PEER], [WORKER], [RELEASE] 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; approved parallel with 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.

Respect the run contract. serial-only stays serial without parallel offers. When the user has requested parallel work (allowed-with-ownership-analysis), the planning ticket proves exact disjoint ownership before sharing a sequence. Required helper/peer/fix/lead-mode exceptions follow their guides.

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. Show the ownership analysis and respect the configured per-project concurrency limit (shipped default 5); the limit is not permission to parallelize shared files. In any doubt → serial.

Three 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; the [FIX] tickets a verifier creates at its own sequence while it parks and waits for them (§5.9); and the [WORKER] tickets of lead mode.

Lead mode — the planner keeps control. After the planner and its peer agreed and your answers are in, a [PLAN] / [REPLAN] ticket may build 2–5 tightly coupled parts itself as the lead, instead of handing them to normal tickets, when keeping its own context matters (planning.md §2b). It writes every shared file first (contracts, routes, config, migrations, package files, the plan), then opens one [WORKER] per part at its own sequence: each with a different job, its own SPEC FILE, its own LOG (.specs/<NNN>-<part>.log) and an OWNS: line listing its files. The platform refuses a worker's file-edit tool outside that line, so no worker writes a shared file or another worker's file. The lead parks with ⏸ WAITING-FOR-ALL-TICKETS #a, #b, … and is woken once, when every worker has replied or ended; it reads each LOG, runs each worker's test group, checks that only owned files changed, and closes the workers. A long phase stays cheaper and sturdier as normal tickets + [VERIFY] + [REPLAN]: every report wakes the lead and it re-reads its whole conversation.

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

Every native work ticket carries: objective and requirement IDs; its actual SPEC FILE path; exact files to read first and files it owns; references to authoritative contract sections/versions; real environment and secret-reference facts; worked acceptance and negative cases; its own and affected test-group commands; known decisions/traps; and required guide sections before the specification material. Do not invent repository paths in a candidate package. No container names/internal IPs, secret values, or duplicated platform operating method.

4.9 Execution mode and flow

Execution mode controls tool approval, not authorization to ignore the workflow. Ticket agents use platform snapshot/git tools, never bare git. Autonomous mode does not authorize deleting project data, bypassing service approval, inventing business decisions or ignoring the chosen ticket 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: <approved mode> · Flow: <relaxed → true | strict → false> · Strategy: <eco|balanced|performance>
• Pace: <standard|fast|ultra-fast> · Parallel: <serial-only|allowed-with-ownership-analysis>
• Plan approval: <autonomous|owner-approves-first-stage> · Releases: <none|at-milestones|every-phase>
• Planning ticket: <provider> · senior_developer (master only if you ask) · <balanced; pro only for a very critical core or documented failure escalation>

📄 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 the phase file .specs/phases/K01.md — the plan file .specs/001-project-plan.md stays a small index of requirements, settings, open questions and phases, the acceptance examples are in .specs/001-acceptance.md, and the baseline gets .specs/000-baseline-index.md, so later tickets read only the parts they need): 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"). Phase creation requires native_creation_authorized=true and plan_approval=autonomous in the ticket's own top-level RUN CONTRACT, plus satisfied scope/input/service gates and closed review helpers. An attachment's flag is not authorization. With owner-approves-first-stage, or without explicit native authorization, show the plan and wait before creating work tickets.

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 phase outline: RepairFlow

This is an illustrative outline for the planning ticket, not a bulk plan for the assistant to create. Assume the active scope and its business decisions are confirmed; list their R IDs and actual capability evidence. Read live providers and their role-specific ledger eligibility before assigning any row.

1. SETUP: prove runtime/database/preview readiness and close only approved environment gaps; configure the application foundation.
2. Access gate: implement and verify the smallest confirmed login/protected-flow slice, including refusals and the operator-controlled administrator procedure.
3. Core slice: create a job, perform its confirmed state transition and deliver it; include that role's help, repeatable tests and worked acceptance.
4. Overdue behavior/notification only when deadline meaning, recipients, cadence and rights are confirmed.
5. Add the required independent verification episodes by risk, pace and provider restrictions; any visual work uses a vision-capable provider.
6. End the phase with REPLAN: the phase's full test run, baseline-plus-ledger comparison and the next stage or final acceptance.

PLAN records initial knowledge itself; there is no mandatory separate knowledge-foundation ticket. Setup/core work uses junior + balanced when moderate; hard authentication/concurrency work uses senior + balanced, pro only for a very critical core. VERIFY and REPLAN normally use senior + balanced. Counts and exact ordering are resolved on the real installation.

4.12 Two ticket descriptions from that plan

Ticket 3 — Application setup (junior_developer, balanced — Moderate):

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).
- Create the non-secret seed records needed by the acceptance examples. The login-delivering ticket
  owns test-account setup. Store long-lived test credentials only through the approved secrets
  procedure and use references; never write passwords in .specs, reports, tickets or knowledge. A
  one-check disposable account may appear only in the approved Browser/HttpRequest call and must be
  revoked immediately afterward.
- 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 family, senior_developer, balanced, 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 the parent's tests (`bash .tests/run.sh 003`). 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 [FIX] tickets for the original builder at YOUR sequence_order — one per finding, or per
small group in the same place, at most 5 (ticket 3's provider; cycle 1 = its role and think mode, then the fix ladder;
no depends_on on you), park with ⏸ WAITING-FOR-ALL-TICKETS #<fix ids>, and re-check the findings yourself when the
fixes reply (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).
• Reports start with NEEDS THE USER: yes|no and OPEN ISSUES AND DOUBTS: ...|none. Missing or contradictory headers are sent back once for correction; a second contradiction waits for the user. Peer/helper/worker tickets are closed by their opener, not the auto-reviewer. A live parking dependency keeps its owner parked. Follow the scheduler facts in ASSISTANT_CLAUDE.md.
• Normal replies wake parked tickets and reach running ones at their next step. wake=false is information-only and wakes nobody. A reply to a completed ticket can reopen it; do not send change notices there.
• 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 subscription usage limit parks the ticket until the limit resets (one notice, a probe at most every 30 minutes, no retry counted), and a daemon restart or an upgrade never uses up a retry. 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 fifteen on-demand guides), the search tools codehero_search_tickets (exact words in the project's tickets), codehero_codebase_query (where a function or class is defined, with its lines; who calls it — when the Codebase Map is on) and codehero_semantic_search (decisions, messages, specs and code by meaning, Greek or English — when semantic search is on), 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. Use the code map and semantic index when available; handle missing or stale results with the core's scoped search/read fallbacks. Do not treat index freshness as proof that a file or change does not exist.

The permission hook sits between the model and every tool call. It enforces the execution mode (Module 4 §4.9), path protection (H5: follow the project's allowed paths and CONTAINER EXECUTION CONTEXT; any permitted additional workspace is inside the container, never on the host; scratch files belong in the project's .tmp/ and custom-service source in its .services/; container routing does not grant permission to edit protected system/platform files, nginx or /opt/services directly), a [WORKER]'s OWNS: line, container routing (a command that would run on the host instead of through crun is refused with the reason, never turned into a question for you), 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 is exempt — polling a ticket, a bare sleep, ProcessManager status, LogTail, or re-reading a growing log with tail / ls / ps (also through crun) — so waiting for a long test run or a parked dialogue is not mistaken for a loop; re-reading the same file with cat / grep still is. On Codex, the reason for any refusal is delivered into the running turn, so the model learns why instead of seeing only "declined". HeroAgent adds per-tool error counters (warn at three consecutive failures, break at five) and a cap of 1000 iterations per run.

Preserve the approved environment_contract in the specification. Ticket instructions describe the project's actual execution environment, project paths, local service ports and secret references; they omit container names, internal container IPs and host-side entry commands. Colocated services use localhost:<verified port>; external services keep their real endpoints. Browser checks use the platform preview URL.

After approval, create the project and its declared platform container and catalog environment through MCP before the planning ticket. nginx is built in and is never declared as an additional service. The planning ticket may discover an approved service gap: its SETUP ticket can install or register it inside the project container under GUIDE: services.md. Missing host runtimes are operator-owned inputs; tickets do not install them.

Destruction, migration, stopping the container, and restoring or deleting a snapshot require the user's explicit yes for the exact operation. For supported container actions, pass user_confirmed=true only after that yes. Never invent a network action or a parameter absent from the live schema.

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, run the ticket's own/affected test groups, 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. Check the actual changed flow on the PREVIEW URL, run your own tests and the groups affected by the change, then record each ACCEPTANCE item as pass, fail or BLOCKED with evidence. VERIFY runs its parents' groups and its own negative checks. The phase's full suite belongs to REPLAN, or an explicit user request; duration is not the trigger for selecting groups.
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. After any compaction — the Claude CLI's or Codex's own, CodeHero's inside a run, or a new round built from CodeHero's summary — the agent gets the same rule (4.65.9): the summary and the SPEC FILE STATUS are its state, it never re-reads everything, and a gap is looked up only where it lives — its own ticket's history (codehero_search_tickets with its id), the code (semantic search, the code map, grep), the decisions — and a guide only by the SECTION its next step needs (codehero_get_guide(name, section=…)). 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.

Since 5.0.0, a ticket agent may fold its own large tool results, calls or messages with codehero_fold and recover needed details with codehero_unfold when folding_enabled permits it. Images are not folded: on API models a screenshot is seen once and then removed from the context automatically (only the agent's description of it stays). API models apply a fold on their next request; Claude print mode, Codex and Grok Build on their next rebuilt run; interactive Claude when its session is rebuilt. Required model reasoning is preserved between runs by the platform. This is ticket-agent memory management; assistants do not configure or operate it for projects, and it is not a reason to copy core instructions into overrides.

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. With semantic search on, storing knowledge first lists similar existing nodes, so the agent updates that node instead of adding a duplicate.

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 (no unexpected network response >=400; an intentional application-level 401/403/422 passes only with the corresponding authorized positive control and an explicit expected-result record; a proxy/WAF refusal is not evidence of application authorization) → 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. An answer that changes or adds a requirement follows guides/update.md: one row in the change ledger .specs/000-changes.md (the log every ticket reads first), the active specs, contracts, tests and knowledge updated, and an information-only notice to every unfinished ticket it touches — you never have to repeat the change to each ticket.

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.

The self-check before the report. The agent first asks itself: can the reviewer close me and let the run go on? Everything done or recorded (a change it made and wrote down, a bug it fixed, a note for the next ticket) is not an open issue — it goes to parts 3/4. What needs you is yes. A technical doubt is solved before the report: another approach, then ONE helper. So NEEDS THE USER: no always comes with OPEN ISSUES AND DOUBTS: none. A report that says no but lists issues, or has no two lines at all, is sent back by the auto-reviewer once (a 📨 SYSTEM (auto-reviewer) message that says what is wrong) instead of being held for you; a second contradictory report waits for you.

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, senior + balanced, basic for a trivial/simple parent, pro only for a very critical parent; apply live provider and ledger restrictions — parent_sequence/parent_ticket_id = the builder; guides/verify-fix.md pre-loaded): walks the parent's acceptance list, runs the recipe and the ticket's own/affected test groups, 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 → only after every check of every parent is done, the verifier creates all the fixes of the cycle together: [FIX] <parent title> (#<parent id>, cycle 1, k/m) — <the finding>, one per finding or per small group of findings in the same place (at most 5 a cycle — a fixer gets one specific problem, which fits its small context) — the original builder's provider, and role and think mode by the fix ladder (cycle 1 = the builder's own, cycle 2 = one think step up, cycle 3 = senior + pro), at the verifier's own sequence_order. Several fixes run in PARALLEL when their files are separate (each with an OWNS: line the platform enforces) and SERIALLY (depends_on the previous fix) when a file is shared. It writes VERIFY: FAIL · cycle 1 · … · fix #<id> on the parent's SPEC FILE, and parks once: ⏸ WAITING-FOR-TICKET #<fix id> (⏸ WAITING-FOR-ALL-TICKETS #<id>, #<id> for several). 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 affected parent groups and the verifier's relevant negative checks), 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 the ways out — (a) one more fix cycle, one step higher; (b) a direct repair: you raise the verifier to master + ultra, it repairs only those findings, and a [PEER] of the other provider family re-checks them and gives the PASS; (c) accept or change the criterion (a business decision, also a row in the change ledger); (d) park the part for a later phase — 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 choose one of its ways out (step 6).

5.10 Helper tickets and the walkie-talkie

Any ticket may open a [HELPER] — on another provider when one is active, otherwise on its own provider, normally senior + balanced, never weaker than the opener; master only on explicit user request — 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; one helper per ticket, carrying all its doubts together. After three exchanges, the owning agent decides a technical issue from the available evidence and records the reasoning. A business decision, scope change, missing input or unresolved required result goes to the user with both views and the concrete decision needed; do not manufacture agreement or a business default. 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. Park on one ticket with ⏸ WAITING-FOR-TICKET #<id> (<number> · <title>) — its reply will wake me. For a set whose results are all needed, use ⏸ WAITING-FOR-ALL-TICKETS #<id>, #<id> (<number> · <title>; ...) — all replies will wake me; wake once after all reply or end. Do not use the single-ticket marker with a comma-list of IDs. 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.

The platform watches the waiting, in both directions (it records which ticket opened which: created_by_ticket_id). A ticket opened by another — a peer, a helper, a worker, a verifier's fix — that ends its turn without answering its creator is reported to the creator with its final report and "if it has not given you an answer, ask it again — something went wrong", and the creator is woken. When a ticket ends its turn and some ticket is parked waiting for it, that waiter gets a 📨 SYSTEM (waiting-check) note and wakes to ask again (at most twice, then it is left for you) — two tickets waiting for each other can no longer freeze a run. Closed tickets are never woken. A lead of workers parks with ⏸ WAITING-FOR-ALL-TICKETS and is woken once, when the whole set is in.

Information-only messages. codehero_update_ticket(ticket_id=…, reply=…, wake=false) delivers a notice marked ℹ️ FOR YOUR INFORMATION that wakes nobody: a waiting ticket reads it when it wakes for its own reason. A ticket that recorded a change of requirement tells the unfinished tickets this way (guides/update.md).

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 — also the only phase of a small project, where it is the final check. 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, the FULL bash .tests/run.sh — the phase's one full run, started first and read alongside) 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, and ALWAYS the peer check); REPAIR NEEDED → a phase of repair tickets (+ their [VERIFY]) ending with a new [REPLAN] — each repair sized like any build (one focused run, ≤ ~12 acceptance items, ≤ ~15 files; a repair that must look at the whole project, such as an inventory of every table or log, is split by area) — 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. The baseline, ledger and current decisions remain authoritative. Use the planning guide's bounded cross-check for unrecorded owner changes, with scoped ticket search and targeted messages; do not reread whole conversations or silently change the baseline. 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:

• &#9744; 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).
• &#9744; The SPEC FILE's ACCEPTANCE list is walked; every item is pass or BLOCKED with a reason; nothing was deleted to look green.
• &#9744; .specs/ STATUS shows the final position; NEXT: is empty or points at the next ticket.
• &#9744; The knowledge graph gained the decisions and dead ends the ticket mentions.
• &#9744; No helper or peer ticket was left open.
• &#9744; The snapshot of the final state exists (backup_log).
• &#9744; 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.
• &#9744; If a VERIFY ticket produced findings: one [FIX] per finding (or small same-place group, at most 5) exists at the verifier's sequence (parallel ones with OWNS: lines, serial ones with depends_on), the verifier is parked on them, 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 family, senior, balanced, 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

Four facts decide how a change propagates:

1. Since 4.66.2, the installed core and the stack sections selected by project_stack load on every run; they are never copied into a project. global_context, project_context and context contain only the user's explicitly requested additions, in the user's words. Do not put the core, a stack section, a guide, a template, an automatically generated project analysis or the specification in these fields. The specification belongs in the planning ticket.
2. The fields reach agents only when additional_context_enabled is on. New projects start on; projects present at the 4.66.2 upgrade start off. Overrides apply above platform defaults, in order global < app < notes.
3. Before clearing legacy content or enabling overrides, read the existing fields, distinguish installed copies from customer additions, show exactly what will change, and obtain the user's confirmation. clear_context_fields=true clears global and app context according to the tool schema; do not assume it preserves customer text or clears notes. Preserve confirmed customer additions. There is no refresh-global-context action. codehero_get_context_defaults is read-only; never copy its result into a project.
4. 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. upgrade.sh also replaces /etc/codehero/heroagent.conf (the previous one is kept as heroagent.conf.bak.<date>). While an upgrade runs (5.0.2), from after its backup until its database, settings and services steps are done, no ticket starts; running tickets go on, and waiting ones start right after.

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.2: a core plus fifteen on-demand guides, loaded by section; the supplied v6.2 core is 47,535 UTF-8 bytes; guide sizes vary by installed version and should be measured, not copied into a standing rule) is written in simple English so that every model, big or small, can follow it. Since 4.66.0 the core also carries the navigation rules for huge projects (find before you read — the code map, scoped search, a document's headings, long outputs into a .tmp/ log) and the rule that every change the user asks for updates every record that states the old behavior; procedures live in guide SECTIONS that the platform loads or the agent opens. Its conventions are not style; they are what makes weak models comply. Keep them when you add or change rules:

Size matters. The supplied v6.2 core is 47,535 UTF-8 bytes and is sent with every ticket; a guide is paid only by the tickets that need it; guide sizes vary by installed version and should be measured, not copied into a standing rule. 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 CORE Section 11, add CHANGELOG.md to the list, and in Section 5's record-update step 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.10): 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 its stack (project_stack=["php", "mysql"]) and put ONLY the difference in project_context, in the team's words — e.g. «This is a Laravel project: artisan commands, routes/web.php, Eloquent + migrations, Blade layouts, php artisan test; ignore the plain-PHP bootstrap and page pattern». The agent reads it as a USER PROJECT OVERRIDE, above the PHP section. Never paste a copy of the PHP section or the core there: since 4.66.2 those load from the installed files on every run, and a copy is refused.
• 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

For an imported project, run codehero_analyze_project and record verified structure and conventions in its map and project knowledge. Put the user's requested change and accepted existing behavior into the planning handoff; preserve the baseline under case D. Write a persistent override only if the user explicitly asks to retain that rule, in their words, after showing the proposed field change. Do not promote an agent's inferred architecture or test recipe into user overrides.

6.8 Worked customization 4 — an API-only project

An HTTP API follows GUIDE: verification.md and GUIDE: testing.md: real requests through the prescribed preview route, persistence/response readback, authorization and validation refusals with positive controls, bounded logs and the affected test groups. An API with no UI does not need a new Browser flow. Native/non-HTTP products follow GUIDE: native.md for the applicable checks.

Put project-specific endpoints, expected results and actual test commands in ticket acceptance and authoritative contracts. Do not write a replacement platform verification procedure into user context fields. A missing or different verification tool is handled by the installed guides, not by an invented api context or core Section 15.

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: keep the business rule and worked example in the unchanged specification carried by PLAN, then its baseline/change ledger and authoritative contract. The planning ticket records the decision in project knowledge and gives each affected ticket its requirement/acceptance references. The project description contains only a short mandate.

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. Test both a new and an existing disposable project. Confirm the next run loads the new installed instruction file; user context fields remain empty or retain only the customer's additions. Check the resolved preview URL in the actual assembled prompt without exposing credentials.
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. Inspect only the specific instruction section needed to confirm loading. Use a redacted or bounded non-secret view of the assembled prompt; never print or attach its database/service credentials, protected paths' values or the complete prompt. Record the instruction source/version and presence once, without credential content.
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. Installed instruction changes reach existing projects on their next run. Do not refresh or paste core/stack text into project fields. Test additional_context_enabled separately with a small explicitly authorized user override, preserving preexisting customer text.
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, a redacted excerpt of only the changed instruction section, containing no credentials, 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. Inspect a legacy project's disabled override fields. Identify old installed copies and genuine customer additions. Propose and confirm a cleanup that preserves those additions; demonstrate installed-file loading and the override switch without copying defaults into the fields.
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.2 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: setup → 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 proposes value-ordered outcomes and optional candidate cards. The planning ticket sizes and schedules the actual phases on the installation; counts are estimates, not quotas. Each planned phase ends in REPLAN. Verification follows risk, size, approved pace and provider eligibility; the package does not prescribe a separate verification ticket after every contract or feature.

7.4 Contracts before code

Write each shared contract once in its authoritative numbered file before creating its consumers. Consumer tickets name exact sections/versions and their owned SPEC FILEs; concise excerpts are labeled references, not independent definitions. The planning ticket creates contract files and knowledge decisions itself. Separate contract/revalidation tickets are not an automatic chain. Update the current contract and every affected record under the change process, preserving history and invalidating affected evidence.

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: owned inputs and the approval/contact gates defined in §2.12. 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. The ticket that completes a role's flow writes that role's help. The last build drafts handover material; the final check completes docs/acceptance.md and docs/handover.md with real evidence. Do not create standalone documentation tickets merely to fill a template.

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

• &#9744; Tickets in awaiting_input: reason? question → answer in one batch; permission → allow/deny; completed (strict) → review the report and close; stopped → correct and retry.
• &#9744; Tickets in failed past retries or stuck: read the last messages, fix the cause (ticket text, environment, credentials), retry.
• &#9744; Helpers and peers left open by finished tickets: close and note.
• &#9744; Count completed failed repair cycles in the verifier's append-only record, not FIX ticket count. The initial finding is not a failed repair. Stop after the same part fails three completed repair cycles, the same acceptance item fails two repairs in a row, or two disputes on one finding, as GUIDE: verify-fix.md specifies.
• &#9744; The replan ticket of the phase: read its plan before it runs if you want scope changes.
• &#9744; Knowledge base growth: decisions and dead ends are being stored (a flat graph after many tickets = context problem).
• &#9744; Snapshots exist for each finished ticket; the latest restores cleanly (test it once per milestone).
• &#9744; 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. Assign each RepairFlow role's documentation to the ticket that delivers its flow, and identify who drafts and who verifies the final handover.
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 for active-scope construction package — its active requirement IDs and readiness evidence stated, not assumed — 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 for delivered flows exists, and acceptance/handover record the actual evidence and owned gaps; 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 instructions omit container names/internal IPs while retaining truthful deployment and execution-context facts? Explain the approved SETUP service-gap exception.
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:

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

---

APPENDICES

Appendix A — Quick reference cards

A.1 Ticket fields

The is_forced and created_by_ticket_id rows describe stored fields; they are not create_ticket parameters.

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). In ordinary scheduling, a higher sequence starts only when every lower one is done or skipped.

A.3 Roles and think modes per ticket type

Size first: a small existing change uses one ordinary build ticket, plus verification when provider restrictions require it. A simple new build (about three screens or fewer, one user type, no login, money, integration or personal data) uses one build and one other-family VERIFY. Larger work uses the approved specification and one PLAN ticket; only that ticket designs and creates the work phases.

A small plan has up to about five work tickets, two review groups, a closing VERIFY and REPLAN, and a peer for applicable risky work. A real plan uses up to ten review groups, a peer and phases of about ten tickets ending in REPLAN. Fast pace uses fewer groups; ultra-fast is an explicitly requested demo with disclosed omissions. Counts are limits or estimates, not quotas. Provider rollout restrictions apply at every pace.

PLAN, REPLAN, PEER, VERIFY and HELPER normally use senior_developer + balanced; a peer/helper is never weaker than its opener. pro is for a very critical core or the documented failure escalation. Work is junior_developer by difficulty: trivial off, very simple fast, simple basic, moderate balanced; hard work is senior + balanced. master_developer is only on explicit request. ultra is never a project default and is not an automatic chain-ticket setting.

FIX cycle 1 uses the builder's role and think mode; cycle 2 goes up one think step; cycle 3 uses senior + pro, never below the builder. Security episodes use senior + pro; performance episodes use senior + balanced, with the specified critical-SLA exception. Release work is senior_developer + balanced (GUIDE: release.md). The planning ticket applies the current guides, pace exceptions, eligibility and user choices.

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_search_tickets · codehero_codebase_query (map on) · codehero_semantic_search (semantic search on) · 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, six 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 · update · helper · debugging · frontend · database · build · testing · verification · coding · native · services · release.

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 on one ticket with ⏸ WAITING-FOR-TICKET #<id> (<number> · <title>) — its reply will wake me + TASK COMPLETED. For a set whose results are all needed, use ⏸ WAITING-FOR-ALL-TICKETS #<id>, #<id> (<number> · <title>; ...) — all replies will wake me; wake once after all reply or end. Do not use the single-ticket marker with a comma-list of IDs. 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"). A ticket you opened that ends without answering → its report + "ask it again". Parked for a ticket that is now waiting too → 📨 SYSTEM (waiting-check). Information only: reply=…, wake=false (wakes nobody).

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.10 — reviewed against CodeHero PRO 5.0.2, Global Context v6.2 and Spec Builder 1.28, 2026-10-15. Current framework files take precedence over this course.

Questions people ask

All the articles ↗

Am I tied to one AI company?

No. CodeHero works with many AI companies at once and with models on your own hardware. You can change company or model at any time — the project, its rules and its history stay. Read the article ↗

Do my passwords and keys reach the AI company?

No. Passwords and keys you store as secrets are used by your application, but their values are never sent to the AI service. Read the article ↗

Why do several AIs work on the same job?

Because one AI does not catch its own blind spots. In CodeHero one model builds and a model from a different company checks; problems go back for repair and are checked again. Read the article ↗

How does CodeHero compare with other AI coding tools?

It is a different kind of thing. Coding tools help a person who writes code. CodeHero does the whole job — asks, plans, builds, checks, hosts and maintains — for the person who knows the business. Read the article ↗

If CodeHero writes the code, what is my role?

You become the advisor: you decide the business rules, approve the plan and accept the result. CodeHero is the developer that asks, builds, checks and maintains. Read the article ↗

How does the AI keep its memory on long jobs?

With memory folding: when the AI has finished with a long result it keeps a short note of what matters and puts the rest away — it can open it again at any time. So it works much longer without losing the thread. Read the article ↗

How does the AI avoid forgetting or getting confused on a big project?

The factory gives it structure: smart tickets with one clear job each, a change ledger of every decision, a map of the code and search by meaning. The AI reads what it needs instead of guessing — which also saves a lot of cost. Read the article ↗

Why do you call it a factory and not a tool?

Because it runs the whole production line on its own — planning, building, independent checking, repair, delivery and maintenance — with stations, rules and records, like a factory. A tool waits for a person to use it. Read the article ↗

How can this change the world of applications?

When the person who knows the work can get software made, checked, hosted and maintained without a development team, software can be made for every business and every need — not only for those that can afford a team. Read the article ↗

What does CodeHero mean for developers?

Less repetitive work and fewer late nights. The factory takes the routine building, checking and fixing; developers decide the architecture, review what matters and handle the hard problems. Read the article ↗

Why does CodeHero host the applications too?

Because building and running belong together. The application runs where it was built, with its domain, secure connection, backups and recovery — and every later change returns to the same factory. No separate hosting panel to learn. Read the article ↗

What technology do the applications use?

Always open, widely used technologies — PHP and MySQL first, and others such as Node, Python or .NET when the job needs them. Your application is never locked into a proprietary platform. Read the article ↗

Why use AI subscriptions instead of paying per use?

Because in our own measurements, for heavy daily work, a subscription has cost up to about 40 times less than paying per use for the same work. CodeHero runs the subscription AI tools (Claude Code, Codex, Grok Build) as workers in the factory. Read the article ↗

What happens to the knowledge about my project?

It is built up and kept inside your installation: decisions, rules, changes and their reasons, next to the code. A new person or a new AI continues from there — the knowledge does not leave with them. Read the article ↗

Can small local AI models do real work?

Inside the factory, yes — more than on their own. Small, clear tickets, a checklist for finishing, tool help and a stronger model that checks the result let small models on your own hardware do much of the building. Read the article ↗