Skip to content

AGENTS.md

Latest commit

 

History

History
161 lines (126 loc) · 5.55 KB

AGENTS.md

File metadata and controls

161 lines (126 loc) · 5.55 KB
Raw

linstash agent instructions

These instructions apply to this repository.

Product vocabulary

  • linstash is the product, repository, and CLI executable.
  • source means the configured Linear workspace.
  • destination means the configured Kan workspace.
  • stash group is an explicit project and status selection policy.
  • stash means copy to Kan, verify, then archive in Linear.
  • Archive is not delete. Never replace Linear's reversible archive mutation with deletion without an explicit product decision.

Start here

  1. Read README.md.
  2. Read docs/README.md.
  3. Check docs/60-work-tracking/active/ for matching focused work.
  4. Read the product, architecture, technical-design, and implementation contracts governing the change.
  5. Inspect the current code and tests before proposing structural changes.

Do not begin from the user request alone when repository evidence can define the current state.

Locked stack

Language: Go 1.25+
Shape: single CLI executable
State: embedded SQLite, compiled with a pure-Go driver
Configuration: YAML without credentials
Secrets: environment variables only
Frontend: none
Server/daemon/webhook/scheduler: none

Do not add a hosted service, background process, Node toolchain, or CGO requirement.

Canonical commands

make test
make check
make build
make verify

Use focused package tests while iterating, then run make verify before claiming repository-level completion.

AI-assisted development lifecycle

Use docs/00-context/ai-assisted-development-workflow.md as the canonical workflow.

For every non-trivial change:

  1. Ground the request in the repository and identify governing durable docs.
  2. Confirm that product behavior and important boundaries are decision complete. Update durable docs before code when they are not.
  3. Use a build specification for milestone acceptance and an implementation plan when sequencing or migration matters.
  4. Create or reuse one bounded active work item for temporary execution state.
  5. Implement the smallest complete vertical workflow; do not accumulate disconnected scaffolding and call it progress.
  6. Update the active checklist only after each item is verified.
  7. Promote stable decisions discovered during implementation into product, architecture, technical-design, implementation, or delivery docs.
  8. Run risk-proportional verification and record exact commands and outcomes.
  9. Close only when the governing completion rule passes; archive completed work or preserve unchecked items under deferred/.

An implementation plan is not proof that work happened. Checked boxes are not proof that behavior works. Tests without the governing acceptance journey are not proof of product completion.

Safety boundary

  • Treat both APIs as external production systems.
  • Read and plan before writing.
  • Do not create destination structures outside configure.
  • Do not archive a Linear issue until its complete selected tree has passed destination read-back verification.
  • Never log API keys, full authorization headers, or issue bodies.
  • Make retries idempotent using source UUIDs and canonical checksums.
  • Stop the affected tree on ambiguous or partial remote state.

Documentation layers

00-context          history, vocabulary, evidence, and workflow
10-product          user-visible behavior and workflow
20-architecture     ownership, boundaries, and data flow
30-technical-design configuration, persistence, and API mechanics
40-implementation   milestone acceptance contracts
50-delivery         release and operator procedures
60-work-tracking    current bounded execution work

Promote durable decisions out of work tracking. Do not use work tracking as a second backlog.

Use the layers consistently:

  • Product docs own what users can do and what the product promises.
  • Architecture owns responsibility and integration boundaries.
  • Technical design owns durable mechanics and invariants.
  • Build specs own milestone scope, acceptance evidence, and completion.
  • Implementation plans sequence delivery but do not redefine acceptance.
  • Delivery docs own release, recovery, and operator evidence.
  • Work tracking owns only current bounded execution state.

When code structure or a durable behavior changes, update the owning document in the same change.

Code organization

cmd/linstash        executable entrypoint
internal/cli        command parsing and presentation
internal/config     configuration model and validation
internal/linear     Linear GraphQL boundary
internal/kan        Kan REST boundary
internal/selection  status and issue-tree selection
internal/migration  orchestration and verification
internal/state      local idempotency and attempt records

Keep API transport types inside their owning adapter. Keep selection pure and testable. The migration service owns ordering and safety; adapters must not silently apply business policy.

First implementation target

The current milestone is the V1 vertical workflow defined in docs/40-implementation/linstash-v1-build-spec.md:

configure
-> doctor
-> plan one explicit project/status group
-> stash one disposable issue tree
-> verify Kan read-back
-> archive Linear leaves before parents
-> rerun as an idempotent no-op

Do not claim V1 complete from CLI parsing, adapters, or unit tests alone. Completion requires the disposable end-to-end acceptance evidence in the build spec.

Commit style

scope: short imperative summary

Preferred scopes: cli, linear, kan, migration, docs, chore.