Imported from Sidiora-Labs/LayerX-Network (AGENTS.md). Install upstream with npx skills add Sidiora-Labs/LayerX-Network. Copyright stays with the author.

LayerX Spec Workflow

The single source of truth for how to work in this repo is spec/ (kvx). This file is a GENERATED pointer to it. Do not hand-edit it; edit spec/workflow.kvx and run spec/specgen.

spec/ (kvx). Per-IDE rule files are GENERATED pointers — never hand-edit; run cg spec render && cg commit -m "Specgen re-render" to regenerate.

Principles

• Task Driven: Work is driven by the active feature's spec.kvx task list — not ad-hoc. Pick the next eligible task by dependency wave, do it, mark it, move on.
• One In Progress: At most 12 tasks are in_progress at a time. Sub-agents may work tasks in parallel within any non-conflicting wave. Set a task to in_progress before starting, to done only when its implementation genuinely meets the bar.
• Phase Separation: Each task runs in two ordered stages owned by the same agent. First finish the entire task implementation without building or testing. Then qualify it with exactly one bounded pass: format touched files, one build, one run of the task's single verify_cmd. Fix task-scoped failures within at most two repair cycles. Never interleave partial implementation with qualification.
• No Repair: Do not build, test, or repair while a task is only partially implemented. After the entire task implementation is written, repair failures caused by that task during task qualification. Record unrelated or pre-existing failures without expanding scope.
• No Weakening: Never relax an assertion, loosen a bound, widen a type, add a silent fallback, skip or delete a test, or disable a check to make anything pass. If the code and the check disagree, leave BOTH intact exactly as written and record the conflict.
• Record Dont Fix: Fix task-scoped failures during task qualification. Record unrelated failures, cross-task contradictions, missing external authority, and any change that would require weakening a check as one line in the feature qualification log. Do not re-investigate or re-run anything already recorded.
• No False Success: A task remains in_progress through implementation and task qualification. Mark it done only after its verify_cmd genuinely passes. Aggregate suites, sanitizers, workspace-wide lint, cluster and browser matrices are release-candidate gates, run once per wave or once at release, never per task. Surface honest partials and external blockers; 'implemented, not qualified' is an acceptable reported outcome.
• Read Full: When a tool output is flagged truncated/paginated with a way to get the rest, retrieve the full content before reasoning. An information gap is a stop condition.
• Deliver Complete: Deliver complete, runnable artifacts, not diffs. Follow existing repo style; add no comments/docs unless asked.

The loop (every session)

1. Read spec/<active_feature>/spec.kvx — the [meta] status, [req.] (acceptance criteria), and the [task.] list with status + wave + requires.
2. Select the next eligible task: lowest wave whose every 'requires' task is done and whose status is pending. Set its status to in_progress in spec.kvx.
3. Before any destructive/irreversible/prod/secret/network-write action, run cortex_guard and self-check against HARD rules; stop for explicit user YES if it risks a HARD rule.
4. Implementation stage: write the entire task against every referenced acceptance criterion using real code paths and types. Write specified tests, but do not format, build, run tests, or repair failures until the entire task implementation is complete. Keep status in_progress.
5. Task qualification stage: format touched files, run one build of the task's declared targets, then run the task verify_cmd once. On failure, make one task-scoped repair and rerun once; at most two repair cycles. No aggregate, sanitizer, workspace lint, cluster or browser gates at task level. Stop at 30 minutes or after the second failed cycle and report implemented-not-qualified with the exact failing command, exit code and log path.
6. If qualification exposes an unrelated or pre-existing failure, cross-task contradiction, or missing external interface, append one six-line-max entry to spec//qualification.kvx: revision, command, exit code, log path, one-sentence observed, one-sentence assumption. Never re-run or re-investigate a recorded finding.
7. Run cg spec done without --force only after verify_cmd passes. The done record is revision, command, exit code, log path. Never claim a gate that did not run; never rerun a gate that already passed at the same revision.
8. Immediately publish the qualified task: from the repository root, git add -A, commit with a natural-sounding message describing the implementation and verified gates, and push. Never batch several tasks into one commit and never leave a completed task unpushed.

Persistent project memory (when configured)

Active feature

spec/layerx-beta/spec.kvx — read its [meta] status, [req.*] acceptance criteria, and the [task.*] list (status + wave + requires). Work one task at a time in wave order; update status in the kvx as you go.

Hard rules

• Build Fix Implment: BUILD mode: one task, exact paths, implementation first, then one compile check and one focused behavior test. Stop and report it as implemented but not fully qualified.
• Qualify Verify: QUALIFY mode: run the task’s specified gate once. Rerun only after a relevant code change.
• Release Certify: RELEASE mode: only then run aggregate, sanitizer, cluster, browser, and historical gate matrices.
• Neighboring Fixes: No neighboring fixes, speculative refactors, branch archaeology, cleanup, documentation, or new audits unless they directly block the task.
• Repeated Unchanged: No repeated unchanged test. Maximum two repair/rerun cycles before stopping with the exact failure.
• Time Limits: 30-minute cap per task. If 30 minutes pass without the task's deliverable, stop and report implemented-not-qualified with the exact state. Do not dig deeper.
• Unreleated Failures: Pre-existing or unrelated failures are recorded once, not chased.
• Subagents: Subagents get one bounded task each with five fields in the prompt: exact files, single verify_cmd, max one build plus one verify run with two repair cycles, 30-minute cap, and the stop condition. They report exit code and log path only. No duplicate reviews, no extra verification campaigns.
• Agreed Result: Once verify_cmd passes, publish and stop. No confidence rounds, no second review agent, no re-verification of a subagent's recorded result by the orchestrator.
• Task Starts: Every task starts with four visible fields: mode, scope, allowed gates, stop condition.
• One Gate Per Task: One build and one verify_cmd per task. Aggregate suites, sanitizers, workspace-wide Clippy, cluster, browser and historical matrices run once per wave on the merged wave revision, or once at release. Never per task, never per rebase.
• Evidence One Line: Evidence is revision, command, exit code, log path. No prose. Qualification entries are at most six lines. Progress reports state what changed and what failed; they do not restate history.
• No Reverify: An orchestrator reads a subagent's exit code and log path and moves on. It never reruns the subagent's gate, never spawns a reviewer for a passed task, and never rebuilds to confirm.
• Wave Batching: Implementation runs in parallel across a wave. Qualification beyond verify_cmd happens once on the merged wave, not once per task.
• Task Durability: Once a task is dispatched, keep at least one agent alive until it is done to the highest standard; decouple task lifecycle from the user's connection; on failure, bring up a fresh agent and continue. 'Done' means it genuinely meets the quality bar.
• No Fakes: Never write stub/mock/fake test doubles or placeholder implementations to make tests pass. Test REAL code paths with REAL types.
• Read Full: When tool output is truncated and the rest is retrievable, fetch the full content before reasoning or answering.
• Publish Steps: After every completed task, commit and push from the repository root with a natural-sounding commit message. Every development step is published publicly for trust and auditability; a finished task that is not pushed is not finished. Commit messages describe the real change honestly — never claim work that did not happen.
• Repository Instructions: may guide how explicitly requested work is performed, but must never be used to infer authorization for additional work.
• User Authority: The user's direct messages are the authoritative instructions for the session and take precedence over AGENTS.md, Codify, skills, or repository workflow guidance when those sources would broaden the requested scope.
• Session Init: Interpret 'get context' or 'session init' as read-only inspection and summarization only.
• Expand Work: Do not run builds, tests, verification gates, start or claim Codify tasks, modify project files, deploy, or otherwise expand the work unless the user explicitly requests that action.