Framework Hub¶

Craft Easy Agentic is the canonical source for the runner script, task templates, and gate configuration that all Craft Easy projects use. The project sync command propagates updates from this repository into every observed project.

What `project sync` copies¶

craft-easy-agentic project sync <slug>        # sync one project
craft-easy-agentic project sync --all         # sync all registered projects
craft-easy-agentic project sync <slug> --dry-run   # preview without writing
craft-easy-agentic project sync <slug> --force     # also overwrite runner-config.yml

Files copied per project:

Source (in craft-easy-agentic)	Destination (in observed project)
`runner/run-backlog.sh`	`tools/run-backlog.sh` (thin wrapper)
`runner/dep-utils.sh`	(loaded by the wrapper from `$CRAFT_EASY_AGENTIC_HOME`)
`runner/translate-stream.py`	(loaded from `$CRAFT_EASY_AGENTIC_HOME`)
`templates/task-spec.md`	`tasks/templates/task-spec.md`
`templates/forundersokning.md`	`tasks/templates/forundersokning.md`
`templates/cross-cutting.md`	`tasks/templates/cross-cutting.md`
`defaults/runner-config.yml`	`tasks/.runner-config.yml` (skipped if exists; use `--force` to overwrite)

The runner wrapper in the project (tools/run-backlog.sh) is a one-liner:

exec "${CRAFT_EASY_AGENTIC_HOME}/runner/run-backlog.sh" \
  --repo-root "$(cd "$(dirname "$0")/.." && pwd)" "$@"

This means runner updates ship automatically — projects always execute the latest runner from the Agentic installation.

Project conventions¶

A Craft Easy project that Agentic observes is expected to have this layout:

<project-root>/
├── tasks/
│   ├── BACKLOG.md                   ← master task list
│   ├── <TASK-ID>/spec.md            ← per-task specifications
│   ├── archive/<TASK-ID>/spec.md    ← completed tasks (moved here by runner)
│   ├── templates/                   ← canonical templates (from sync)
│   ├── .runner-config.yml           ← project-specific gate overrides
│   ├── .tasks-state/
│   │   ├── backlog-runner.log       ← append-only event log
│   │   ├── runner.pid               ← runner process PID
│   │   ├── runner.lock              ← flock singleton guard
│   │   ├── cost.log                 ← per-session cost tracking
│   │   ├── locks/<TASK-ID>.lock     ← active task marker (pid inside)
│   │   └── logs/<TASK-ID>.log       ← per-task agent output
│   ├── .stop-backlog                ← graceful stop signal
│   ├── .pause-backlog               ← pause signal
│   ├── .pause-backlog-resume-at     ← unix timestamp for auto-resume
│   └── .pause-backlog-reason        ← manual | rate_limit_5h | …
├── tools/
│   ├── run-backlog.sh               ← project runner wrapper (from sync)
│   └── translate-stream.py          ← stream-json translator (from sync)
└── .craft-easy.toml                 ← optional path deviations

Any task-ID prefix is accepted: PL-, AP-, fim-, CE-, etc.

BACKLOG.md format¶

- [ ] [PL-T302](PL-T302/spec.md) — Implement operator handbook
- [ ] [PL-T303](PL-T303/spec.md) — M2M service account (beror på: PL-T289, PL-T293)
- [x] [PL-T291](archive/PL-T291/spec.md) — Infrastructure verification

Unchecked [ ] = ready to run (if deps satisfied)
Checked [x] = completed (runner moves spec to archive/)
beror på: TASK-ID, TASK-ID = dependency declaration (scheduler blocks this task until all deps are [x])

Model routing (`Modell:`)¶

Each task spec declares which Claude model to use:

**Domän:** API / Backend
**Modell:** `claude-opus-4-7`
**Risk:** HIGH

Model selection policy¶

Model	When to use
`claude-opus-4-7`	Default — implementation, refactoring, debugging, design, integration, multi-file changes, complex tests, anything non-trivial
`claude-sonnet-4-6`	Only pure renames, format-only commits, doc-only updates without logic changes, simple single-file text updates

Haiku is never used for task implementation.

Default fallback¶

When a spec is missing the **Modell:** field the runner falls back to $DEFAULT_MODEL (Opus). Earlier builds ran a "router" Claude call to classify Opus vs Sonnet for fieldless specs, but that serialised a full LLM round in front of every "new" task (5–30 s extra) and was mostly dead code — chat-Claude always sets the field at spec creation. Removing the router shaves that latency from every task spawn.

Spec-creation conventions¶

When chat-Claude (running on Opus) generates a new spec, it sets **Modell:** based on its judgment of complexity. Most tasks land on Opus; the few that don't are documented inline in the spec ("doc-only update — Sonnet sufficient"). You can override by editing the field manually before starting the runner.

Per-project deviations (`.craft-easy.toml`)¶

Projects that need non-standard paths declare them in .craft-easy.toml at the project root:

framework_version = "0.3"

[paths]
runner_script = "scripts/agent.sh"     # default: tools/run-backlog.sh
backlog       = "specs/BACKLOG.md"     # default: tasks/BACKLOG.md
state_dir     = "tasks/.state"         # default: tasks/.tasks-state
tasks_dir     = "tasks"
archive_dir   = "tasks/archive"
owner_todo    = "tasks/OWNER_TODO.md"

[notes]
deviations = "Free-form description shown in the overview UI."

All paths are optional — omit any path that matches the default. Most projects need no .craft-easy.toml at all.

The Agentic server reads this file at startup and uses the declared paths for all file-watching and state-reading operations.

For human-readable deviations (policy decisions, intentional non-compliance), document them in the project's own CLAUDE.md under ## Avvikelser från craft-easy. This is the convention for deviations that Agentic itself does not need to act on programmatically.

Task templates¶

Three templates are synced into every project's tasks/templates/:

`task-spec.md`¶

The master task specification template. Contains ~20 sections covering acceptance criteria with file:line proof mapping, data model, API/UI contracts, OWASP security checklist, per-tenant test matrix, performance and accessibility budgets, and a six-phase Definition of Done gate checklist.

Recent additions imported from airpark-legacy lessons (April–May 2026) raise the honesty pressure without adding new runner gates:

Section	Purpose
§3.1 Spec-lucka-scan	Mandatory table where every spec sentence is articulated + the agent's interpretation + its guess + "needs answer?". Forces tacit guesses to surface. Done first in Fas 0, before inventories
§5b Data-flöde-trace (UI → backend)	Complement to §5a (backend → frontend). For every UI flow that sends data: trace UI → API wrapper → DTO → service → repo → DB. A single ✗ anywhere = the feature is "silently broken". The classic airpark catch: UI displayed "Discount code TEST −50%" but `discountCode` was never sent
§12d Parallel-path-konsistens	Table for operations that exist in multiple places (Stripe/Swish/Invoice, tenants, auth flows). Each row should be identical or have explicit motivation for any difference
§15b Konfidens-bedömning (klar-gate)	Risk-adjusted threshold (LOW ≥ 90% / MEDIUM ≥ 95% / HIGH ≥ 97%). The agent must write a free-text statement of what the confidence is based on and what creates uncertainty — checkbox-green is not enough. "Code looks correct" is explicitly insufficient. HIGH requires two independent review passes
§18.1 Ready-to-use adversarial-review prompt	Complete `Agent({...})` prompt to copy, with 8-point find-bugs assignment. Output saved as `tasks/{TASK-ID}/review.md`
§18.2 7 ytliga-granskning fällor	Concrete catalogue to actively scan for in Fas 4: data-flow silence, null DI service, missing DTO field, parallel-path divergence, spec-text vs code-state, validation vs operation, too few review passes

See Task Specification for the full format.

`forundersokning.md`¶

Pre-implementation investigation template. Filled by the agent as Phase 0 of the task workflow before writing any code. Contains:

Explicit execution order: spec-gap scan FIRST, then classification and category questions
Task classification (13 categories: api-endpoint, data-model, auth, ui-portal, ui-mobile, cms, cross-tenant, integration, i18n, infra, data-migration, feature-flag, compliance)
Spec-gap scan (what's ambiguous or missing from the spec)
Risk matrix (impact × likelihood)
Universal questions (8, apply to every task — including parallel code paths and end-to-end data flow)
Per-category deep-dive questions (10 questions per category)

`cross-cutting.md`¶

Quality requirements that apply to every task regardless of domain: - Performance (API p95, frontend bundle size, database index requirements) - Accessibility (WCAG 2.1 AA, keyboard navigation, screen reader) - Responsiveness (mobile-first, tested at 375px, 768px, 1280px) - Error handling (HTTP status codes, user-facing messages, logging) - Security (OWASP A01–A09 for every API change) - Internationalisation (i18n keys, no hardcoded strings, date/currency formatting)

The runner includes cross-cutting.md in the agent prompt context so requirements are always applied, even when not explicitly stated in the task spec.

Re-syncing after template updates¶

When canonical templates / runner / defaults change, observed projects need to re-run sync to get the new versions for new tasks. Existing task spec files are not migrated:

craft-easy-agentic project sync --all

The CHANGELOG.md of craft-easy-agentic flags template changes and tells you when to re-sync.