Agent Guide

Agent guide

This page is a deterministic orientation path for Claude, Codex, and other coding agents. Treat repository state and tests as authoritative; documentation narrows where to inspect but does not replace inspection.

For any generated-template task, the mandatory entry point is the Template-Agent-Guide. Resolve the exact bounded context from praxis.config.json instead of attempting to load the whole Wiki indiscriminately.

First five minutes

1. Read README.md for supported product surface.
2. Read Terminology, Architecture, and Code-Architecture.
3. Inspect git status before editing; this repository may be shared by concurrent sessions.
4. Identify whether the task belongs to cli/, web/, docs/, or root orchestration.
5. For generation behavior, trace configuration → resolver → selected manifests → composer → tests.

Task routing

Task	Start here	Then inspect
Add/change CLI option	cli/src/cli/command.ts, runCreate.ts	schema, answers, help tests
Add standard framework/provider	cli/src/config/schema.ts	resolver, matching template manifests, matrix tests
Add Pro capability	cli/src/config/pro.ts	resolver, capability module, Compose/K8s/Terraform manifests, Pro tests
Fix generated file	output praxis.config.json	resolved modules, overlay source, all patches targeting file
Change UI style	cli/scripts/ui/	generated ui.<style>, previews, UI quality/matrix tests
Change local gallery	cli/src/ui/	templates/ui.catalog, gallery browser tests
Change website	web/	web/package.json, Vercel config, web build
Change Wiki	docs/	renderer, link checker, Wiki workflow

Generation trace algorithm

When asked “where did this generated code come from?”:

1. Validate/read the output's praxis.config.json.
2. Apply resolveModules mentally or in a focused test.
3. Preserve module order.
4. For each module, filter manifest entries using AND selector semantics.
5. Map root/frontend/backend scope for the project type.
6. Find the first overlay that creates the file.
7. Find later overlays with replace: true and patches targeting it.
8. Include merged package/env contributions.
9. Confirm the conclusion with an existing or new generation test.

Invariants not to break

• Validate before resolution and composition.
• Do not overwrite existing destination directories.
• Keep composition atomic and confined to staging/output roots.
• Keep module order deterministic.
• Reject dependency/script conflicts rather than silently winning.
• Make replacement explicit.
• Preserve reusable patch anchors when later modules depend on them.
• Record effective configuration in every output.
• Keep requested and resolved Pro capabilities distinct.
• Do not add Angular JavaScript output.
• Do not hand-edit generated UI matrices as the primary change.
• Do not include UI authoring design sources in the published npm package.
• Do not describe the legacy pro branch as architecture; Pro lives in cli.

Common reasoning mistakes

“Every template generates a backend”

False. frontend has no backend. backend and fullstack use Express. pro-backend uses Django or Gin. UI templates only replace frontend landing-page files.

“A module directory means it is active”

False. Only resolver-selected modules and matching manifest entries contribute.

“A capability is one file”

Usually false. A capability can span application code, env keys, package dependencies, Compose patches, Kubernetes resources, Terraform, tests, and docs.

“Generated code uses a Praxis runtime”

False. Praxis writes standalone framework code; the CLI is not a runtime dependency.

“Fix the generated artifact directly”

Often wrong. For UI artifacts, fix the canonical renderer/profile. For manifest outputs, fix the owning overlay or patch. Add a regression test at the source boundary.

Safe change checklist

1. State the intended supported configuration(s).
2. Add/adjust a failing focused test.
3. Make the smallest source-of-truth change.
4. Generate a representative project and inspect the real files.
5. Run the focused test and applicable toolchain build.
6. Run the full relevant matrix/gate from Testing.
7. Update docs if configuration, module ownership, generated topology, or extension rules changed.
8. Stage only files belonging to the task.

Machine-readable anchors

Agents should prefer these stable data sources over prose lists:

• supported standard values: exported constants/types in cli/src/config/schema.ts;
• Pro capability order/implications: cli/src/config/pro.ts;
• UI style IDs/metadata: cli/src/ui/catalog.ts and cli/templates/ui.catalog/catalog.json;
• module declarations: cli/templates/*/manifest.json;
• published package allowlist: cli/package.json#files;
• CI truth: .github/workflows/ci.yml and ui-matrix.yml.