Building with Agents

CloudSeed keeps system intent in version control so humans and agents can find the same contracts, change the implementation, and check whether the result still meets those contracts. Start at the repository's AGENTS.md and load only the context relevant to the work.

Context and ownership

Each fact has one canonical home. Routers and skills link to contracts; they do not maintain another copy. The shared docs are published from this repository. Colocated feature contracts are read in the checkout and are not automatically served by the public docs site.

Foundation owns enduring purpose, actors, outcomes, and boundaries. Keep requirements focused on intended behavior and constraints. Architecture owns technical choices, rationale, and implementation limitations. Verification defines human-readable acceptance criteria from the requirements and architecture. Tests implement those criteria and provide evidence that they hold; test implementation and coverage audits remain separate.

Add context when it preserves consequential intent, a constraint, or a non-obvious decision. A small feature can use one concise document; a simple helper may need none. No folder needs a full set of requirements, architecture, glossary, and review files by default.

A worked example: authentication

The authentication slice demonstrates the complete route through context:

1. Root AGENTS.md routes auth work to src/auth/AGENTS.md.
2. That local router links src/auth/FOUNDATION.md, src/auth/REQUIREMENTS.md, src/auth/ARCHITECTURE.md, src/auth/VERIFICATION.md, and the applicable shared docs.
3. Foundation explains why auth exists; requirements define observable behavior; architecture describes how to satisfy the requirements; verification defines acceptance criteria; the actual implementation, including its tests, must satisfy those criteria.
4. An agent changes the affected implementation and checks those contracts through the existing test suite.

For example, replay acceptance says that when several requests try to verify the same unused link concurrently, exactly one succeeds and at most one session is created. The tests must demonstrate that outcome. The criterion remains the same if the token storage, verification handler, or test framework changes.

The hierarchy is Foundation → Requirements → Architecture → Verification acceptance criteria → Actual implementation. Each stage is constrained by the stages before it; the actual implementation includes application code and tests. Audit the test assertions against the criteria; do not derive acceptance from whatever the existing tests happen to cover. The development guide owns commands and shared setup.

Using the durable context skill

The repo-local durable-context skill defines the context to preserve—foundation, requirements, architecture, and verification—then explains how to discover, create, and maintain it. Ask your agent to use it, or have it open .agents/skills/durable-context/SKILL.md directly if the harness does not discover that location. Claude Code also has a symlink under .claude/skills/ to the same source.

The skill works without the author's personal dotfiles. It follows the repository's owners and current task authority, preserving unknowns and conflicts instead of inventing decisions or changing requirements to match a bug.

Change lifecycle

changes/ is temporary working context for active projects. Durable docs describe the accepted system; proposed behavior remains in the active project until accepted. Small, clear changes can use the task or PR directly instead of creating a project folder.

When finishing a project:

1. Verify the accepted outcome with the relevant checks and record material verification gaps.
2. Carry enduring purpose, behavior, constraints, and technical rationale into their durable owners. Update verification and discovery links with them. Distinguish implemented behavior from deployed state.
3. Preserve any actionable followups in the adopting project's task tracker. Keep implementation limitations in architecture and acceptance criteria in verification; report remaining coverage gaps in task or review evidence; execution logs and abandoned implementation details do not belong in durable context.
4. Remove the completed project's artifacts from the codebase as part of finishing the project. Do not retain them in an in-repository archive. Committed history remains recoverable through Git; preserve necessary information from uncommitted artifacts before removing them.
5. Check that no current docs, skills, or instructions still depend on the removed artifacts.

Keep workflow instructions and reusable templates under changes/; remove the project-specific folders when their work is complete. Do not remove an active, partially implemented, or unrelated project to satisfy cleanup. Historical folders should be reconciled within a scoped cleanup before removal, rather than treated as current contracts or blindly deleted.

Context updates belong with the accepted implementation. A later code change should leave readers able to understand the current system without reopening its completed project plan.

Adapting the starter

Update the overview for your product's users and outcomes, then add contracts where your product has meaningful behavior or risk. Keep shared constraints with their shared owner and feature-specific rules with the feature. Use root and local routers to expose those owners as the application grows.

The docs renderer serves an explicit list of top-level Markdown pages. Register a new public page in src/docs/docs_views.rs and verify it with cargo test --lib docs::. The separate public website copies docs/ with its sync-docs command and maintains its own navigation list; publishing there requires updating that snapshot and navigation. Keep repository-relative source links in repository context and use /docs/<slug> links between rendered public pages.

For the ideas behind this approach, see Durable Context, Disposable Code and Context Architecture.