Walden

Walden

Author and review deliberately; delegate workflow mechanics to the CLI. Reply in the user's preferred language. The skill supplies judgment, not approval on the user's behalf.

Entry Decision

Before creating a feature or choosing a phase, inspect the request, applicable project rules, and existing contracts. Read .walden/constitution.md and relevant .walden/lessons.md when present. When an approved .walden/contracts.md exists, start discovery from it: read in full only the features it identifies as related, then follow their citations as needed. Do not create a spec merely because the user mentioned Walden.

A bugfix can restore an approved contract without changing it. A refactor can preserve it. Neither route bypasses tests, evidence checks, or execution authorization. An explicit request to implement a maintenance fix authorizes that work; approval of a planning document alone does not.

Before closing maintenance, identify the applicable current contract, run existing tests, and refresh the selected affected evidence with walden verify <feature> at the declared checkpoint. Use --all only for a justified forced check. Inspect the CLI outcome; raw test output alone does not refresh evidence. If no spec covers the change, state that limitation without creating a spec merely to obtain a checkbox.

For an existing portfolio, establish applicability within the user's requested scope before proposing adoption or replay:

Ground proposals in decision sources. Age, missing fingerprints and completed checkboxes do not establish obsolescence. Requirements can survive an outdated implementation plan. A current requirement does not make its historical bootstrap/deployment task a current regression check: inspect the actual proof before proposing replay. If it records one-time delivery work, propose the needed current baseline/regression contract for review, not automatic backfill plus execution merely because the CLI reports a re-prove count. Code describes observed behavior, not authority to rewrite intent; a newer draft does not automatically supersede an approved contract. If sources conflict, ask before retiring or changing the contract. A case-study request yields general findings for the product being improved, not unsolicited operations in the example repository.

For existing specs, use CLI status and validation rather than guessing freshness. For a new spec, use CLI-generated scaffolds as the canonical document templates. Do not reconstruct full templates from memory.

CLI Prerequisite

Requires Walden CLI v0.10.4 or a newer compatible release. Before the first CLI operation, check command -v walden and that executable's version --json. If PATH has no usable compatible CLI, check $HOME/.local/bin/walden too (on Windows: Get-Command walden and %USERPROFILE%\go\bin\walden.exe). Reuse a compatible binary by its verified path or a session-only PATH correction; do not downgrade it or edit persistent shell configuration. An unclear version is not assumed compatible.

If the CLI is missing or incompatible, stop the dependent Walden operation. This guide never installs the CLI: do not run an installer, fetch a script or binary, or write install commands for the agent to execute; installation is the user's action in their own terminal. Determine the platform (uname -s on POSIX shells; PowerShell, $env:OS, MSYS/MINGW mean Windows) and run command -v go (PowerShell: Get-Command go) so the branch below is a lookup, not a question to the user. Then name one path:

• go resolves (any platform): go install github.com/andrearaponi/walden/cmd/[email protected] as a single command block, then make sure $(go env GOPATH)/bin (Windows: %USERPROFILE%\go\bin) is on PATH.
• go does not resolve, macOS/Linux: open https://github.com/andrearaponi/walden — the README has the one-line installer and the releases page has the binary. No command block: you do not carry that installer line.
• go does not resolve, Windows: download walden-v0.10.4-windows-<arch>.exe from https://github.com/andrearaponi/walden/releases, rename it to walden.exe and place it on PATH.

If the user then asks you to install anyway, restate once that you do not install and repeat the same single pointer or block — exactly one block per reply, never the other branch, never a fetched script. Do not repeat the refusal a third time; do not fetch anything. Do not substitute manual workflow metadata for the missing CLI.

This guide is distributed through the Skills CLI and the CLI binary is distributed separately; neither installs, inspects or updates the other. Update the guide with npx skills update walden; update the binary with walden update or the README installer. Do not look for a Walden command that installs, removes or reports the guide: none exists.

Ownership And Authorization

• Resolve the CLI prerequisite above before any Walden operation. Bootstrap consent does not approve specifications, authorize task execution or permit publication; never invent a replacement state machine.
• Never hand-edit workflow frontmatter, timestamps, fingerprints, checkboxes, or evidence contents. Edit document bodies; use the CLI for state mutations. Preserve schema and extension fields already present in scaffolds.
• Never treat silence as approval. Present the relevant document and wait for explicit approval before review approve.
• Planning stops at approved tasks. Implementation of the plan requires an explicit execution request; it is not an automatic consequence of approving tasks.
• Waivers require the user's explicit approval of the pending scope and reason in the current conversation. Never supply --allow-pending for convenience.
• Retirement requires explicit user confirmation. Do not delete superseded specs or evidence as housekeeping.
• For a non-trivial request, state a short plan and its verification steps. If constraints conflict, a proof fails, or the spec is insufficient, stop and re-plan from the earliest affected phase.
• Before authoring, ask for stable project context if an existing constitution contains only placeholders. Do not manufacture the project's stack or rules.
• A fingerprint binds approved content, not semantic correctness. Good requirements, meaningful proofs, and human review remain necessary.

Command Lookup

Use commands for mechanics; use walden --help and command help for syntax details. Read JSON results and warnings, not just a green-looking summary.

Commands support --json, including failures. The envelope contains schema_version, command, ok, and result; inspect warnings and command-specific fields. Do not re-implement it or infer success from stdout alone.

Authoring Phases

After the entry decision, locate .walden/specs/<feature>/. Use the earliest missing, unapproved, or stale phase. New features always start at Requirements. Existing work may enter Design only with fresh approved requirements, and Tasks only with a fresh approved design.

Use the same review loop in each phase:

1. Read upstream content and relevant lessons; draft or revise the current body.
2. Validate the current phase and resolve structural defects and meaningful warnings.
3. Open its review through the CLI, present the document, and ask for approval.
4. After explicit approval, seal it through the CLI and proceed only within the user's requested scope.

Do not mechanically approve multiple phases from one vague acknowledgment. If implementation reveals a contract gap, pause, revise the earliest affected document, reconcile, and re-walk the affected review gates.

Decision Checkpoint Protocol

Apply during requirements, design, and task drafting, not execution.

• Bifurcation Test: checkpoint only when a different choice would discard or substantially rewrite downstream content. When inconclusive, default to autonomous resolution.
• Explore before asking: check the codebase, constitution, and approved upstream documents. If they resolve the choice, record <!-- assumed: <choice> (source: <file or document>) --> and continue.
• Checkpoint: insert [decision: <question>], explain the fork, recommend an option with a one-line rationale, and stop generating dependent content. If no option is defensibly better, do not fabricate a preference.
• Resume: explain how the user's answer will be applied before continuing. A newly exposed significant fork gets its own checkpoint before dependent content is written.
• Autonomy: if the user delegates a checkpoint decision, record <!-- assumed: <choice> --> and proceed without further checkpoints for decisions within that delegated scope.
• Budget: no more than five checkpoints per phase drafting session. Keep unresolved checkpoints in draft; do not open phase review while one remains unresolved.
• Ordinary assumptions: record <!-- assumed: <choice> --> inline without interrupting the user.

Requirements

Once intent is sufficiently clear to select authoring, draft first, then iterate. User stories explain context; the acceptance criteria are the contract.

• Give requirements stable IDs (R1), criteria stable IDs (R1.AC1), quality attributes NFR1, and constraints C1. Do not renumber IDs already referenced elsewhere.
• Write each AC in EARS with one observable response. The CLI validates keyword structure, not the quality or completeness of the behavior.
• Include explicit out-of-scope items when scope risk is high. Do not split a feature automatically because its AC count crosses a threshold; reconsider cohesion and scope instead.
• Attach one short Acceptance check: continuation below each AC. Describe the observation separating success from failure, not a chosen framework or implementation command. If that observation cannot be stated, clarify or rewrite the criterion before requesting approval.

After every revision, including restoring original AC wording, inspect all presented criteria and preserve or reattach their acceptance checks. Keep the requested EARS sentence unchanged where appropriate; its separate check continuation is explanatory content, not a new behavior requirement.

Quality checks during drafting:

• Form: invariants need no invented user trigger. Prefer “The system SHALL assign distinct identifiers” to “WHEN the user starts, ...” for an always-on uniqueness rule.
• Atomicity: split “generate the record and deliver the notification” into independently observable criteria. Check each response before drafting the next; the word “and” alone is not proof that two behaviors exist.
• Specific events: prefer “WHEN an OrderCreated message arrives” or “WHEN a lease expires” to “WHEN processing happens.” API and background events are as valid as clicks or submissions.
• Failure coverage: for each realistic constraint failure, identify the required response. Storage requirements need read, write, and relevant failure behavior, not only a happy-path save.
• NFR promotion: “IF the connection fails, THEN ... reconnect” is behavior and belongs in an AC; retain the resilience attribute as the NFR.
• NFR bridge: connect each NFR to testable ACs. “Accessible” needs concrete keyboard/screen-reader outcomes; a resource limit can need an internal measurement rather than an invented UI interaction. Ask about vague quality claims.

Minimal criterion example, not a document template:

1. `R1.AC1` WHEN a lease expires, the system SHALL release its lock.   - Acceptance check: another holder can acquire a lock after its lease expires.

Read ears_validation, ears_distribution, and warnings from walden validate --json. Review form appropriateness, response atomicity, specific events, realistic failures, NFR bridges, persistence balance, and domain-specific gaps. Counts are diagnostic, not a quota; zero unwanted forms may indicate missing failure handling. Use the normal review loop before Design.

Design

Read approved requirements. Research external facts only where a decision depends on them. Use the CLI-generated design scaffold rather than inserting a standard long architecture document.

Exactly six headings are required by the current kernel:

• Architecture
• Options Considered
• Simplicity And Elegance Review
• Failure Modes And Tradeoffs
• Verification Plan
• Requirement Coverage

Other sections — components/interfaces, data models, error handling, security, testing strategy, diagrams — are optional expansions for relevant decisions, contracts, or verification needs. Do not add empty sections to demonstrate thoroughness.

Compare with a real alternative. When no meaningful alternative or discussion applies, give a one-line reason rather than inventing complexity. Requirement Coverage and Verification Plan still need substantive mappings and checks; non-applicability is not a way to omit them.

Challenge the first draft once: could a simpler shape or less coupling satisfy the same contract? Record real failure modes and accepted tradeoffs. Wrap every requirement/NFR ID in the coverage table in backticks: the validator expects rows such as | `R1` | ... |.

If design exposes new scope or missing acceptance behavior, return to Requirements. Otherwise validate and use the review loop before Tasks.

Tasks

Read approved requirements and design. Keep work incremental and testable, with at most two hierarchy levels. Each executable leaf names its AC IDs, design references, and verification steps. Use the canonical scaffold and minimal syntax below, not a copied full plan.

- [ ] 1. Implement and test the behavior  - Requirements: `R1.AC1`  - Design: Architecture  - Verification:    - command: ["go", "test", "-v", "-count=1", "-run", "^TestExample$", "./pkg/example"]      expect_output: "--- PASS: TestExample"      covers: ["R1.AC1"]

Top-level leaf metadata uses two spaces; child tasks use two-space task indentation and four-space metadata. Proof steps sit two spaces deeper than Verification:, and attributes two spaces deeper than their command.

Assign proofs to sensible groups of criteria rather than running the same broad suite for every checkbox. An already-green suite is not proof of newly introduced behavior: each implementation leaf must include its corresponding new assertions before it can complete. Do not postpone those tests to a later leaf while claiming new ACs through an unchanged old PASS marker. Use a direct assertion or a new test-specific selector/marker that cannot pass before the intended check exists. A proof step asserting ACs must name them in covers:. If sequencing exposes a missing interface or untestable step, return to Design. Validate and request task-plan approval; then stop unless explicit execution was also requested.

Proof Authoring

Before presenting a task plan:

1. Actual assertion: every step has an explicit pass condition; exit zero alone is useful only if the command actually asserts the intended property.
2. Non-vacuity: prevent a passing run with zero intended tests. Use native fail-on-no-tests behavior, structured test results, or an appropriate output assertion. Go's -run may match nothing successfully: use an anchored selector, -v, -count=1, and the named PASS output as shown above.
3. Read-only re-verification: assertions must not alter the worktree. Prefer go mod tidy -diff over go mod tidy; route build/generator outputs outside the repository. A missing file or failing assertion must not be “repaired” by its proof.
4. Bounded execution: each step has a 10-minute default timeout. Declare a positive timeout: for a justified different budget, such as timeout: 30m. Expiry fails the step.
5. Declared coverage: covers: names known asserted AC IDs, not a promise that the command is semantically sufficient. Inspect task-reference and proof-reference coverage separately.
6. Reproducible conditions: use known inputs and relevant environment probes. Do not disguise environment failures by weakening the approved proof.

Commands are JSON argv arrays, executed without implicit shell interpretation. Pipes, redirects, and operators require an explicit shell, for example command: ["sh", "-c", "test -d src && test -f src/main.go"]. Use expect_exit: 1 for a genuinely negative assertion. expect_output is a substring of combined output, not a regular expression. Multi-step proofs stop on the first failure.

The old single-line Verification: go test ./... format cannot express quoting, shell operators, or attributes; use structured steps for new work. Do not retrofit approved proofs outside an authorized revision and re-review cycle.

Execute And Recover

For an explicitly authorized task or batch:

1. Read the three approved documents. Use task status and task start for readiness and context; never implement an unapproved or stale plan.
2. Declare the authorized batch scope and its verification checkpoint, then implement with focused tests. Do not run the full suite unless requested or included in the approved verification plan. If no task/batch was identified, resolve the next task and ask before implementing.
3. Complete through task complete, not a manual checkbox. The CLI executes proofs and records evidence before moving completion state. Complete children before containers.
4. Commit evidence with the work only when committing is authorized and project policy permits it. This skill does not grant permission to commit, open PRs, tag, or publish.
5. Inspect evidence warnings, but ordinary repo-wide stale-code after an edit is not a reason to replay every completed prefix. Bring targeted checks forward for a changed dependency, failed proof or contract gap; otherwise aggregate re-verification at the declared batch, feature or delivery checkpoint. Every leaf still earns its own completion proof. At an intermediate pause keep the batch and residual staleness explicit; at closure finish code, README and other deliverables before the final scoped verification, then inspect the release verdict and report any deferred gaps.

TDD describes development order, not a passing proof. When TDD is required, observe a runnable behavioral assertion fail before implementing the behavior; minimal compilable scaffolding is fine. Compile/import failures and named PASS output do not establish that sequence. If code already exists, report tests added afterward or a test-driven repair accurately. Do not break and restore existing code to manufacture retrospective TDD; label mutation testing separately.

A document-body edit breaks its approval seal. reconcile resets affected approval state; review the changed chain again. Re-approving identical content does not stale downstream content. Missing legacy fingerprints need adoption or reconciliation, not hand-written seals.

Completion can legitimately run a generator and records the resulting tree. Re-verification is different: its proofs are read-only. verify --check prevents ledger writes, not command side effects. A detected mutation or missing required identity contaminates that run: later executions cannot earn verified evidence even if the bytes are restored. Investigate the named cause; after any authorized proof repair/re-review, use a new clean verification of the affected scope. Never automatically roll back user source.

Evidence states are derived: verified, stale-spec, stale-code, failed, unattested, unrecorded, and pending. Inspect binding, code freshness and execution-integrity provenance separately, including gaps hidden by state precedence. unattested means required assurance is missing, not a newly observed code failure. A recorded passed is not enough for current verification. Intended contract changes need the affected review cycle and new proofs; code-only maintenance need not create a new spec. Committing unchanged bytes does not by itself stale code evidence; use the CLI's reported differences rather than guessing the cause.

Environment context

Optional .walden/environment.md probes use argv, for example - go: ["go", "version"] and - node: ["node", "--version"]. Names are lowercase kebab-case; platform and walden are reserved profile keys. Probes share a 30-second budget. Malformed declarations fail evidence-producing commands; failed or timed-out probes yield diagnostic marker values.

Profiles are diagnostic, not a state gate or proof of producer policy. Compare environment drift before blaming code; never weaken an assertion to hide a version mismatch. When the request forbids environment probes, use the read-only adopt <feature> assessment rather than evidence status.

Adoption and retirement

adopt assesses existing Walden specs, not an arbitrary codebase into a specification. After establishing the current contract, present its non-executing plan: backfill, re-prove, complete, or blocked are technical classes, not business applicability. A recovered binding does not attest old execution purity. complete means nothing to adopt, not that all product work is implemented. No upgrade or inspection automatically replays the portfolio.

Backfill trusts recorded approval and seals the current body; disclose that intervening pre-fingerprint edits cannot be detected. Present contradictions require human reconciliation. Apply runs real proofs: request it only for the reviewed scope, retaining the feature selector. New v1alpha2 ledgers can contain untouched legacy records; use a compatible CLI and never delete or downgrade evidence to satisfy an old reader.

When available, read adoption's workload as declared steps, not tests or an ETA: unavailable features are separate from known zero, and counts do not authorize execution. After apply, retain per-task diagnostics and read accepted execution (passed), final state and integrity separately. evidence_persisted: false means observed results were not saved; a feature error before any attempt creates no task result. elapsed_ms measures the current attempt or enclosing feature/invocation, not historical cost. These fields may be absent on older compatible CLIs; absence is not zero. Protect redirected diagnostics, which may contain command output; Walden adds no automatic logs or timing history. Inspect the available failure reason before proposing a diagnostic replay.

Retirement requires explicit confirmation. Before deletion, verify that Git preserves each spec/evidence file at a recoverable last-live commit, identify the reason and successor, and agree where any surviving requirements belong. Missing history or an unresolved mixed contract means stop, not fabricate recovery or create an unauthorized commit. Do not offer history-free deletion as an equivalent Walden retirement or a waiver of its recovery prerequisite. Then remove only the authorized files and record name, date, reason, last-live commit and successor in .walden/RETIRED.md. The optional walden-history companion can assist; it is not required, and retirement does not independently authorize committing or publishing.

Consolidation

Keep the portfolio consistent in small steps rather than auditing it after dozens of specifications. status warns when a consolidation is suggested or due: two and three specifications whose approved requirements changed since the last one. feature init and release check repeat the due warning without blocking. If walden consolidate --help is unavailable in the installed CLI, skip this section.

When it is suggested or due, or the user asks, run walden consolidate. Read .walden/contracts.md and only the features in the reported scope; for features linked only through widely cited files, their view entry is usually enough. Then compare every added, changed or removed statement in the report's comparisons with the linked statements the report shows beside it: report each contradiction, duplicated rule or dependency on a removed or changed statement with both qualified identifiers. The comparison is the material to check, so there is no need to read unrelated specifications in full. Record the outcome under ## Coherence Review in .walden/contracts.md: one ### <feature> entry per pending feature with the inconsistencies found, or none, citing the linked statements you compared as feature#ID in inline code; the CLI refuses to open or approve the view while an entry is missing, empty or cites none of them. Look for overlaps, contradictions, removals still cited elsewhere and obsolete obligations, and report each with its qualified identifiers. Deterministic findings are leads, not verdicts.

Propose every fix as a revision of the affected specification through its normal review path. A consolidation authorizes no other work: never approve, retire or execute anything as part of it. Then update the view for the scoped features: Purpose: (one line on what the feature guarantees today), Active: (the identifiers the report lists), Reserved: (removed identifiers; keep reserved identifiers listed for good), Sources: and Related:. Run walden consolidate open, present the view, and run walden consolidate approve only after the user's explicit approval. If status reports the view stale, review it and run walden consolidate open again. The CLI owns the record and the review state: never edit .walden/consolidation.json or the view frontmatter by hand.

In an existing portfolio, walden consolidate start records today's approved specifications as an unconsolidated backlog. Consolidate backlog features in small batches when the user asks, never all at once.

Release judgment

When asked about releasability or a delivery hand-off, use release check; do not invent a verdict from separate status summaries. The command judges existing state and never publishes. Produce evidence with verify separately.

Pending work blocks by default. A user-approved partial delivery may use --allow-pending --reason "..."; it never waives missing legacy assurance or strict input binding. --strict compares the actual judged spec/evidence bytes and presence with one captured commit, even for ignored files. Non-strict output does not claim that local metadata is committed. Uncommitted code has no bypass, and usable git is required.

Report scope, guarantee, blockers, completion class, commit and waiver accurately. A selected-feature pass is not a repository-wide certificate. Unclassified/unassessed features cannot disappear from a whole-portfolio claim; exclusion requires explicit scope selection or authorized retirement. Do not equate reference coverage or a stored pass with formal correctness.

Lessons And Summaries

Review relevant lessons before similar work. User corrections, rejected drafts, failed validation, re-planning, or unexpected execution failures prompt an internal decision about a reusable lesson. Log meaningful patterns with walden lesson log: trigger, lesson, and a guardrail that would prevent repetition. Do not turn ordinary expected TDD red tests into a list of invented mistakes.

Describe the observed trigger accurately. If the user first requested A+B and later keeps only A, record “scope narrowed from A+B to A,” not “the agent invented B.” Do not claim two behaviors shared one AC if they were already separate. Lessons preserve facts and useful guardrails, not invented mistakes. Quote or closely paraphrase the actual non-sensitive scope clarification for the trigger: “requested” is not “approved.” A user may request a preventive lesson without any mistake having occurred; label it as preventive rather than reconstructing a failure story.

A newly logged lesson gets a short user-facing entry with its practical guardrail. With no new lesson, omit lesson-status output entirely; the internal decision still happens.

Summaries should state what changed, what was actually checked, unresolved blockers, and the next required user decision. Distinguish planned, executed, failed, and not-run checks. Be concise and do not confuse approval of the current phase with permission for later phases or publication.