Skip to main content

Recover Existing Intent

Use this flow when a repo already has useful intent artifacts, but they are hard to find, address, or hand to an agent.

You do not need ds adopt for this. Today, ds scan, ds map, ds recent, ds find, and ds context can already index and retrieve existing plans, PRDs, RFCs, ADRs, specs, docs, and agent notes in place.

If you already know the goal, start with the task:

ds task "implement the bounded change"

Use the trust layer when you need orientation first.

Map System Boundaries​

ds map

ds map shows architecture or system boundaries DevSpecs can infer from local files, tests, docs, and git history. It indexes that evidence before mapping the repo, including on the first run. It is for onboarding and orientation, not for executing a task.

Recover Recent Direction​

ds recent

ds recent shows recently active local work, boundary hints, and follow-up context commands. It merges overlapping recent topics and demotes generic maintenance noise where there is stronger source-backed work. Use it after returning to a repo or before trusting older plans.

Inspect Evidence​

ds find "oauth redirect"

ds find builds packed context by default: source, tests, docs, receipts, and excluded noise. Use --plain only when you want flat ranked results.

ds find "oauth redirect" --plain

Export One Exact Artifact​

ds context <artifact-id>

Use IDs from ds find, ds show, or JSON output when you want one exact plan, spec, ADR, or task artifact as paste-ready agent context.

Cold Indexing​

The first run in a large repo can take seconds while DevSpecs builds local SQLite state. Non-quiet progress goes to stderr so normal stdout and JSON output remain script-safe. Use --verbose when you need detailed scan phases, and use --quiet for result-only automation.

Planned: Adopt Existing Artifacts​

ds adopt is planned, not shipped. It is not required for brownfield search or packed context. The intended role is to create optional wrapper artifacts for teams that want older intent files to become explicitly addressable and versionable without rewriting the originals.

Expected shape:

ds adopt --dry-run
ds adopt --all
  • detect candidate intent artifacts during map/find/scan flows;
  • show a dry run before writing anything;
  • create thin wrappers for addressability and metadata;
  • leave original files untouched by default;
  • make wrappers easy to version when they should become durable team context.