Skip to content

docs(sdd): compress SDD skills and add filesystem path convention notes #1004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
glats wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −36
Open

docs(sdd): compress SDD skills and add filesystem path convention notes #1004

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 21 additions & 36 deletions internal/assets/opencode/sdd-orchestrator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,32 +69,6 @@ These are parent-orchestrator stop rules. When a trigger fires, perform the spec

If multiple rows match, run the narrow set that covers the risk. Example: shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.

#### Review Execution Contract

**Exhaustive first pass.** Loop until dry: sweep the diff repeatedly until N consecutive sweeps yield zero new findings, then stop; the loop MUST be finite. Default N = 2 consecutive dry sweeps. R2 Readability MAY use N = 1. Hard ceiling: 4 sweeps regardless of N.

**Findings ledger.** Emit a findings ledger with this schema for every entry:

| Field | Values |
|-------|--------|
| `id` | `{LENS}-{NNN}` (e.g. `R1-001`) |
| `lens` | risk \| readability \| reliability \| resilience \| judgment-day |
| `location` | `path/to/file.ext:line` or `:start-end` |
| `severity` | BLOCKER \| CRITICAL \| WARNING \| SUGGESTION |
| `status` | open \| fixed \| verified \| wont-fix \| info |
| `evidence` | why it matters |

If the first pass finds nothing, persist an empty ledger record rather than skip persistence.

**Ledger persistence honors the artifact store.**
- `openspec`: write `openspec/changes/{change-name}/review-ledger.md`.
- `engram`: upsert topic `sdd/{change-name}/review-ledger` (ad-hoc judgment-day without a change: `review/{target-slug}/ledger`, where `target-slug` = `pr-{number}` when reviewing a PR, else the current branch name kebab-cased, else a kebab-case slug of the user-stated review target).
- `none`: keep the ledger inline in the response; do not write files or Engram artifacts — the ledger lives only in this conversation; complete the review → fix → re-review loop within the session because it is not persisted across compaction.

**Scoped re-review.** A re-review pass takes the persisted ledger and the fix diff as input. It MUST verify each ledger finding's resolution and MUST review only fix-touched lines; it MUST NOT re-read the full original diff. A finding on an untouched line MUST be logged with status `info` as a first-pass quality signal and MUST NOT by itself trigger another full round.

**Execution mode.** Inline mode (this adapter has no dedicated review-*/jd-* subagents): run each lens sequentially inside your own orchestrator context and maintain the merged ledger directly.

#### Cost and Context Balance

- Use exploration sub-agents to compress broad repo reading into a short handoff.
Expand All @@ -113,6 +87,11 @@ SDD is the structured planning layer for substantial changes.
- `hybrid` -> both backends; cross-session recovery + local files; more tokens per operation
- `none` -> return results inline only; recommend enabling engram or openspec

> **Filesystem path convention**: Engram topic keys use the `sdd/` prefix for
> memory organization — this is NOT a filesystem path. The canonical filesystem
> directory for SDD artifacts is `openspec/`. Never reference `.sdd/`, `sdds/`,
> or bare `sdd/` as filesystem paths. These do not exist.

### Commands

Skills (appear in autocomplete):
Expand Down Expand Up @@ -263,24 +242,30 @@ The gatekeeper runs in addition to the Review Workload Guard and the Mandatory D

### Artifact Store Mode

This is collected by `SDD Session Preflight`. If missing, enforce the hard gate before any phase work. Ask which artifact store they want for this change:
This is collected by `SDD Session Preflight`. If missing, enforce the hard gate before any phase work. Ask using this EXACT question text:

- **`engram`**: Fast, no files created. Artifacts live in engram only.
- **`openspec`**: File-based. Creates `openspec/` with a shareable artifact trail.
- **`both` / `hybrid`**: Both - files for team sharing + engram for cross-session recovery.
```
2. Artifact Store: Where should SDD artifacts (proposals, specs, designs, tasks) be persisted?
- openspec/ -- filesystem only (openspec/<change-name>/) (Recommended)
- engram -- Engram persistent memory only
- hybrid -- both filesystem AND Engram
```

If the user doesn't specify, detect: if engram is available -> default to `engram`. Otherwise -> `none`.
**CRITICAL**: `openspec/` is the canonical filesystem path for SDD artifacts. Do NOT use `sdds/`, `sdd/`, or `.sdd/` in the option text. Engram topic keys use the `sdd/` prefix for memory organization only.

Cache the artifact store choice for the session. Pass it as `artifact_store.mode` to every sub-agent launch. If the user doesn't specify, detect: if engram is available -> default to `engram`. Otherwise -> `none`.

Cache the artifact store choice for the session. Pass it as `artifact_store.mode` to every sub-agent launch.

### Delivery Strategy

This is collected by `SDD Session Preflight` as the chained PR strategy. If missing, enforce the hard gate before any phase work. Ask which delivery/review strategy they want:
This is collected by `SDD Session Preflight` as the chained PR strategy. If missing, enforce the hard gate before any phase work. Ask using this EXACT question text:

- **`ask-on-risk`** (default): Ask later if `sdd-tasks` forecasts high risk or >400 changed lines.
- **`auto-chain`**: If forecast is high, continue with chained/stacked PR slices without asking again.
- **`single-pr`**: Prefer one PR; if forecast exceeds 400 lines, require `size:exception` before apply.
- **`exception-ok`**: Allow a large PR because the maintainer explicitly accepts `size:exception`.
```
3. Chained PR Strategy: How should delivery be packaged?
- single-pr -- one PR with all changes (Recommended)
- chained -- multiple stacked PRs (for changes over 400 lines)
```

Cache the delivery strategy for the session. Pass it as `delivery_strategy` to `sdd-tasks` and `sdd-apply` prompts.

Expand Down
4 changes: 4 additions & 0 deletions internal/assets/skills/sdd-init/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y
- Always build `.atl/skill-registry.md`; also save `skill-registry` to Engram when available.
- Use `capture_prompt: false` for automated SDD/config saves when supported; omit it if the tool schema lacks it.
- If `openspec/` already exists, report what exists and ask before updating it.
- When presenting filesystem persistence options to the user, use `openspec/` as the canonical path label. NEVER use `sdds/`, `sdd/`, or `.sdd/` as filesystem paths. Engram topic keys use the `sdd/` prefix for memory organization only — that is NOT a filesystem path.

## Decision Gates

Expand All @@ -60,6 +61,9 @@ Run this phase when the orchestrator/user asks to initialize SDD in a project. Y
1. Inspect project files (`package.json`, `go.mod`, `pyproject.toml`, CI, lint/test config) and summarize stack/conventions.
2. Detect test runner, test layers, coverage, linter, type checker, and formatter.
3. Resolve Strict TDD from agent marker, `openspec/config.yaml`, detected runner fallback, or no-runner fallback.
3.5. Resolve artifact store mode if not passed by orchestrator:
- If `artifact_store.mode` was provided (engram/openspec/hybrid/none), skip this step.
- If NOT provided, ask the user using the EXACT question template in `references/init-details.md` section "Mode Selection Question Template". Use `openspec/` as the filesystem label — NEVER `sdds/`, `sdd/`, or `.sdd/`.
4. Initialize persistence for the resolved mode.
5. Build `.atl/skill-registry.md` using the skill-registry scan rules.
6. Persist testing capabilities and project context.
Expand Down
13 changes: 13 additions & 0 deletions internal/assets/skills/sdd-init/references/init-details.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,19 @@ openspec/
| Formatter | ✅ / ❌ | {command or —} |
```

## Mode Selection Question Template

Use this EXACT question when `artifact_store.mode` was NOT passed by the orchestrator:

```
Where should SDD artifacts (proposals, specs, designs, tasks) be persisted?
1. Hybrid - Engram + openspec/ (Recommended)
2. Engram only
3. openspec/ only
```
Comment on lines +100 to +105

@coderabbitai coderabbitai Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Label the fenced question block.

The unlabeled code fence trips markdownlint (MD040). Mark it as text so the template stays lint-clean without changing the prompt text.

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 100-100: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@internal/assets/skills/sdd-init/references/init-details.md` around lines 100
- 105, The fenced question block in init-details.md is missing a language label,
which triggers markdownlint MD040. Update the fenced block around the SDD
artifact persistence question to use the text label, using the existing prompt
section so the content stays unchanged while the markdown becomes lint-clean.

Source: Linters/SAST tools


**CRITICAL**: `openspec/` is the canonical filesystem path. Do NOT substitute `sdds/`, `sdd/`, or `.sdd/`. Engram topic keys use the `sdd/` prefix for memory organization only.

## Output Templates

For each mode, include project, stack, persistence, Strict TDD Mode, Testing Capabilities table, artifacts created/saved, limitations where relevant, and next steps. Engram mode must mention local/non-shareable limitations; none mode must recommend enabling persistence.