lindoelio/spec-driven-steroids/contextual-stewardship

Contextual Stewardship Skill

You are acting as a Staff Engineer responsible for Contextual Stewardship — a knowledge graph system that captures, retrieves, and manages architectural decisions, business rules, and workflows across projects with full provenance tracking and lifecycle management.

Core Concepts

Domains

All rules are classified into one of 8 standard domains:

Custom domains are also supported — any string not in the standard list is accepted as a custom domain. Child domains inherit from their parent (e.g., architecture.database inherits from architecture).

Lifecycle States

Rules transition through three states:

• active — Rule is currently in effect
• deprecated — Rule is superseded by another; supersededBy link is set
• archived — Rule is no longer relevant; preserved for historical reference

Storage Backend

The system uses JSON file storage for all rule persistence:

CLI Commands

All stewardship operations use the sds stewardship CLI command. Ensure sds (spec-driven-steroids) is installed and available in PATH.

sds stewardship <subcommand> [options]

retrieve — Pre-flight Context Retrieval

When to use: Before implementing a feature, writing code, planning architecture, or making a technical decision. This is the mandatory pre-flight check.

Behavior:

1. Verify file system storage is available
2. Query the semantic retrieval engine with the current task keywords
3. Apply scope chain priority: session → project → global. Project scope defaults to the current project directory name.
4. Return rules scored by weighted keyword match (50%) + recency (30%) + confidence (20%)
5. Filter to active rules by default; surface deprecated rules with supersededBy link
6. Flag out-of-domain matches only when no in-domain results exist

Command:

sds stewardship retrieve <query> [--domain <domain>] [--scope <project-id>] [--global]

Use --scope <project-id> when working outside the project directory. Use --global only for rules that should apply to every project.

Retrieval confirmation format:

• "Retrieved N rules from {domain} domain via {tier}. Score breakdown: keyword={k}, recency={r}, confidence={c}."
• "No in-domain results — found {n} cross-domain matches (flagged [out-of-domain])."
• "Running in {tier} mode."

store — Persist a Decision

When to use: When the user explicitly establishes a new pattern, makes a technical decision, or defines a business rule.

Behavior:

1. Validate domain (must be standard or accepted custom domain)
2. Persist to project scope by default, using the current project directory name
3. Require --global for rules that are truly universal across all projects
4. Auto-assign default expiration: 2 years from now
5. Run conflict detection — flag rules with similarity > 0.85
6. If conflict: surface to agent for override / merge / cancel decision
7. On confirm: write rule node with full provenance (source, sourceFile, decisionDate, author, originalText)
8. Archive previous version on every update

Command:

sds stewardship store <domain> --content "<content>" [--author <name>] [--scope <project-id>] [--global]

Before storing, classify scope explicitly:

• Use project scope for repository-specific architecture, business rules, implementation details, naming, validation, or workflow nuances.
• Use global scope only for durable preferences that are safe across unrelated repositories.

Persistence confirmation format:

• "Rule created: {ruleId} (project:{project-id} or global)."
• "Conflict detected — similarity {score} with rule {conflictId}. Choose: override / merge / cancel."
• "Rule superseded link set: {oldId} → supersededBy → {newId}."

extract — Auto-capture from Specs

When to use: After reading a design.md or requirements.md file. Automatically propose decision rules extracted from spec elements.

Behavior:

1. Parse design.md: extract DES-* headings, Mermaid technology mentions, _Decisions: blocks
2. Parse requirements.md: extract glossary terms, SHALL/MUST constraints, REQ-* bodies
3. Infer domain from content using keyword analysis
4. Dedupe by content hash (avoid storing exact duplicates)
5. Present candidates to agent for explicit confirmation before persisting
6. Store confirmed rules with provenance linking to spec file path and element ID

Command:

sds stewardship extract <file-path> [--author <name>]

Extraction confirmation format:

• "Found {n} extraction candidates from {filename}. Review required before persistence."
• Candidate format: [{elementId}] {domain}: {content-preview...}
• After confirmation: "Stored {n} rules from spec. Provenance: {filename}#{elementId}."

inject — Phase Context Injection

When to use: Before entering a new spec-driven phase (requirements, design, tasks, implementation). Automatically retrieve and inject relevant context.

Behavior:

1. Map phase to relevant domains:

• requirements → business, workflow
• design → architecture, security, performance
• tasks → workflow, team-structure
• implementation → architecture, technical-debt

1. Query semantic engine for phase-relevant rules
2. Resolve project-scoped rules before global rules unless --global is passed
3. Format as injected context block
4. Offer-to-capture: if a decision is made mid-phase, prompt to store it

Command:

sds stewardship inject <phase> [--scope <project-id>] [--global]

Injection format:

• "Phase {phase} context injected: {n} rules available from {domains}."

manage — Lifecycle and Rule Management

When to use: When explicitly asked to list, deprecate, archive, or reclassify rules.

Commands:

sds stewardship manage list [--scope <scope>]
sds stewardship manage list --global
sds stewardship manage deprecate --ruleId <rule-id> [--scope <project-id>] [--global]
sds stewardship manage archive --ruleId <rule-id> [--scope <project-id>] [--global]
sds stewardship manage move --ruleId <rule-id> --scope <project-id>

Use move to reclassify an active global rule into a project scope. The source global rule is archived after the project-scoped copy is saved.

capabilities — Check Current Tier and Features

When to use: Debugging or verifying why a certain feature is unavailable.

sds stewardship capabilities

Output example:

Tier: tier2-json-graph
File System: available
Enabled Features: json-graph, semantic-retrieval, versioning, conflict-detection

trace — Rule Lineage Lookup

When to use: When investigating the history or provenance of a specific rule.

sds stewardship trace <rule-id> [--scope <project-id>] [--global]

Returns: rule content, domain, state, full provenance, supersededBy link, and version history with timestamps and diffs.

Pre-flight Retrieval Checklist

Before every implementation task, run through this checklist:

• [ ] sds stewardship retrieve "<task keywords>" — do we have project rules or global fallback rules?
• [ ] Check scope chain — project rules should override global rules. Use --scope <project-id> if the current directory is not the target project.
• [ ] Check for conflicts — does the new decision contradict an existing rule?
• [ ] Check deprecated rules — is there a supersededBy link to follow?
• [ ] Store new repository-specific decisions without --global; reserve --global for universal rules only.
• [ ] sds stewardship extract <spec-file> if reading design.md or requirements.md

Storage Backend

The system uses a single, file-based JSON graph storage backend:

• Storage location: ~/.agents/stewardship/global/{state}/ and ~/.agents/stewardship/projects/{project-id}/{state}/, where {state} is active, deprecated, or archived
• Version history: Stored under the matching scope directory in .versions/{ruleId}.json
• Format: Individual JSON files per rule for easy inspection and version control
• Conflict detection: Enabled with similarity threshold of 0.85

Confirmation Message Quick Reference