schematics

Imported from leafCreations/schematics (AGENTS.md). Install upstream with npx skills add leafCreations/schematics. Copyright stays with the author.

Agent guide — structure_scripts

Start here for Cursor agents. Agent mode requires a kanban card, valid labels, and an agent verb (implement, update, spawn, …) — see kanban-card-gates.mdc. review … only or no card → Ask-only (read-only).

Thin always-on orchestration: .cursor/rules/agent-routing.mdc.
Full process: .cursor/skills/agent-triage/SKILL.md → work → .cursor/skills/agent-self-evaluation/SKILL.md.

Do not use docs/roadmap.md as the task queue.

Default: kanban-first

Ignore Backlog unless the user names a backlog card. On QA-complete / Done, the agent moves cards to done/ + Card Done same turn (feature/bug/agent/commit-issue); inquiry / feedback → move only — reference § QA-complete triggers.

No implementation without a card — no surgical/ad-hoc fixes.

Card label gate

Every card must have a recognized labels entry (inline JSON array). Invalid (missing, labels: [], unknown) → stop; user must set feature, bug, agent, inquiry, plan, commit-issue, or feedback.

Card types (labels in frontmatter)

Resolve Feature Areas → Product + Tests + Docs via docs/feature-areas.yaml:

python scripts/resolve_feature_areas.py "Render Preview"
python scripts/resolve_feature_areas.py --handlers "Open Structures Workflow"
python scripts/resolve_feature_areas.py --lessons "Render Preview"

Every turn (non–Ask mode)

1. Classify   → reference § Classify; triage §1 — card + label → one scoped kanban-*-cards.mdc
1b. Failure   → triage §1b grep (signals only)
2. Discover   → reference § Discovery ladder; ≤3 reads then grep/search
3. Work       → Product + Tests + Docs → prior lessons gate → Decisions/CA; Review QA → **QA follow-up**
4. Verify     → ruff E501 on touched `.py`; staged pre-commit-pytest.sh
5. Done       → QA-complete → agent moves `done/` + Card Done (kanban-markdown § Card Done; ff cadence fcp2);
               `build_lessons_index.py` when lessons ran; `build_forward_feedback_index.py` when lessons ran or
               **`feedback`** spawned (Signature: `forward-feedback-card-done-ingest`)
6. Self-eval  → agent-self-evaluation §7; ≥1 skill + ≥1 rule on implementation turns

Detail: agent-triage/SKILL.md, agent-routing.mdc.

Maintaining AGENTS.md (routing guide)

Agents MUST evaluate this file every turn (self-evaluation §2b check 4). Signature: governance-thin-agents-md — epic history lives in yaml/reference, not here (acb3).

Scoped rules: agent/kanban skill edits → agent-agents-md-maintenance.mdc. Governance globs → self-eval §6g. Periodic audit: reference § Epic audit — create_governance_audit_card.py (optional). Drift: reference § Drift alert examples.

If behavior changed but AGENTS.md is stale → handoff Context load: AGENTS.md stale: … and fix when possible.

Classify quickly

Full signal table: agent-triage/reference.md § Classify — Signature: governance-compact-classify-ssot. Edit reference only; ≤5-row summary:

Area → skills & rules (load when touching)

Yaml-synced — agents_skill / agents_rules in docs/feature-areas.yaml are parity SSOT (sync_agents_area_table.py --check). Signature: governance-area-schema-agents-table-sync.

Path→test: agent-triage/reference.md. Hook SSOT: scripts/pre-commit-pytest.sh.

Repo layout (one screen)

structures/{name}/structure.yaml          # manifest
structures/{name}/stage{N}/stage.yaml     # stage + layer_files
structures/{name}/stage{N}/layers/*.yaml
ui/                                       # grep main_window.py — do not read whole file
registries/                               # behaviors, palettes, catalog
renderers/ + render_main.py               # blueprint / preview / worldgen
helpers/
.devtool/features/                        # kanban To Do (agents)
docs/feature-areas.yaml

Implementation gates (kanban)

Before in-progress → review on feature/bug/agent cards:

• Product + Tests + Docs complete (no _TBD_ at Review)
• Prior lessons gate + **Prior lessons (YYYY-MM-DD):** on card
• Staged scripts/pre-commit-pytest.sh green; docs/feature-areas.yaml + Docs updated
• All Acceptance Criteria [x]

Inquiry → Response on card → review. Review QA fixes: kanban-markdown § User-reported QA fixes.

Card Done: kanban-markdown § Card Done + reference § Forward-feedback capture cadence — agent moves on QA-complete; lessons for feature/bug/agent/commit-issue.

End handoff (required every turn)

Full template: agent-self-evaluation §7 — Signature: governance-compact-self-eval-handoff. Last sections: optional Card Done / epic blocks per §7; then ### Files used then ### Self-evaluation (one line per field).

Implementation turns: edit ≥1 skill and ≥1 rule (§6).

What not to do

• Implement product code without card + agent verb
• Edit on review-only prompt (review @card without update/implement/spawn)
• Card Done lessons/ff on inquiry or feedback cards
• Pick work from Backlog or docs/roadmap.md without user direction
• Full pytest after every small edit; read all of ui/main_window.py
• Web-search Minecraft 1.x — use project-context (26.x)
• Skip self-evaluation, Files used, or dual skill+rule updates on implementation
• Python lines > 100 chars (Ruff E501)