Menu
Purpose: Interactive planning dialogue that produces a Brief artifact before architect and engineer
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Apply when the user mentions any software development work: implementing features, fixing bugs, reviewing or refactoring code, debugging, testing, deploying, working with agents or subagents, making architecture decisions, setting up projects, managing dependencies, writing scripts, or any task that involves reading, writing, or reasoning about code and systems.
Agentic Engineering Protocol for Hermes - structured delegation model, risk classification, adversarial review loops, code quality gates, git workflow conventions, and named agent definitions. Load this skill when doing AI-assisted software development with Hermes Agent.
Apply when the user mentions any software development work: implementing features, fixing bugs, reviewing or refactoring code, debugging, testing, deploying, working with agents or subagents, making architecture decisions, setting up projects, managing dependencies, writing scripts, or any task that involves reading, writing, or reasoning about code and systems.
Pre-implementation technical design agent. Spawn when you need a structured technical plan before writing code. Reads the codebase, identifies patterns and constraints, evaluates approaches, and produces a concrete plan a Worker can execute directly. Never writes or modifies files.
General-purpose implementation agent. Spawn for any code change: new features, bug fixes, refactors, configuration changes, or script writing. Reads the codebase to understand conventions, implements the change, runs quality gates, and returns a clear summary of what was done. This is the standard Worker for all Elevated-risk implementation tasks.
Cheap per-turn stop-condition check for open-goal loops. Spawned by the conductor ONLY after an Elevated iteration produces a clean Skeptic sign-off, to evaluate the operator-declared goal_condition and return continue-vs-stop only - never for a Low/Trivial iteration (no Skeptic sign-off exists to run after; the conductor evaluates goal_condition directly there instead). Tier 1 (haiku) leaf agent - read-only, no subagent spawning, never runs in place of, before, or concurrently with a Skeptic review. Does NOT review correctness or safety and does NOT raise, waive, or comment on Skeptic findings. Returns BLOCKED only as a structural guard when spawned without a confirmed Skeptic sign-off; the conductor handles this BLOCKED as a fallback to direct evaluation, NOT as the generic Worker-BLOCKED-means-cap_reached-escalation semantics in content/references/subagent-protocol.md - a BLOCKED return here never halts the loop. On any other failure (unavailable, errored, timeout, malformed output) the conductor falls bac
| name | ds-brief |
| description | Purpose: Interactive planning dialogue that produces a Brief artifact before architect and engineer |
| user-invocable | true |
Run the Activation preflight from
METHODOLOGY.mdbefore proceeding. If inactive, no-op and exit.
Interactive planning dialogue. Produces a Brief at docs/planning/<slug>.md via a
structured multi-turn conversation, then hands off to the architect and engineer with
brief_path pre-populated in the execution contract.
Session budget note: Brief sessions are structured multi-turn conversations that track state in brief-session.json. Each gray-area resolution consumes conductor turns. Complex Briefs with many gray areas can drive long sessions that accumulate stale state. The conductor SHOULD recommend /ds-wrap after resolving 10+ gray areas in a single session, or when the total conductor turn count approaches the soft limit defined in content/references/subagent-protocol.md Section 13.
The conductor monitors operator messages for planning-intent signals. When detected, it
auto-invokes /ds-brief using the surface-and-proceed pattern.
Surface-and-proceed announcement (auto-trigger only):
"Starting /ds-brief for [topic] - reply STOP to abort or skip the dialogue."
"One turn" definition: one operator message and the conductor's immediate response. STOP must appear in the very next operator message after the conductor's announcement; otherwise the conductor proceeds.
Explicit invocation /ds-brief [topic] works identically but skips the announcement.
Signal must be exploratory framing, not execution. When ambiguous, prefer NOT firing.
When the problem, users, or scope are still fuzzy - or the project has no docs/overview/vision.md / docs/overview/requirements.md yet - spawn the product-discovery agent first. Discovery decides WHAT to build and WHY (the problem, the personas including the counterparty, the market context, the staged vision and requirements); /ds-brief and the architect decide HOW. Run discovery, let the operator ratify and promote the staged intent layer, then return to /ds-brief to frame the execution. Skip discovery and go straight to /ds-brief only when the problem and scope are already clear.
If the operator passes a PRD document, the conductor skips intent-capture and jumps to PRD extraction (Section 5). Replace the standard announcement with:
"Found PRD - extracting Brief fields."
On invocation, if .agentic/brief-session.json exists:
If status: interrupted (or dialogue_active with updated_at more than 10 min ago):
"Interrupted /ds-brief session detected for ''. Last phase: [status], [N] gray areas answered. Resume this session or start fresh? (resume / fresh)"
Parse-failure branch: if file is unparseable:
"Brief session state file is corrupted. Start fresh? (yes/no - if no, please move/delete the file manually and retry)."
If /ds-brief received no topic argument, conductor asks:
"What are you trying to build or solve? One or two sentences is enough to start."
Operator replies. Write brief-session.json with status: intent_captured.
Run the prior-decisions scan (Section 7) after intent is captured but before presenting the gray-area menu.
Slug derivation. Convert the operator's intent statement to a slug:
Example: intent "I want to build an interactive planning command" -> slug build-interactive-planning-command.
The same slug derivation algorithm applies in implement-ticket.md Phase 0b (when deriving slug from ticket title, the ticket-ID prefix is also stripped). For /ds-brief, no ticket prefix exists - derive directly from intent.
Conductor reads the intent and generates 4-8 SCOPE-SPECIFIC gray areas inline (no subagent spawn). These must be concrete decisions, not generic checklists.
Examples for "user authentication": session handling, error responses, multi-device policy, recovery flow. Examples for "CLI for db backups": output format, flag design, progress reporting, error recovery.
Present as a numbered menu:
"Here are the areas where scope is still open. Pick the ones you want to talk through (e.g. '1, 3, 5'), or 'all' to cover everything, or 'none' to skip to the Brief draft:
- [gray area]
- [gray area] ..."
Write brief-session.json with status: menu_presented and the gray_areas array.
One exchange per selected gray area (selected: true in the state file):
dialogue_log in the state file.gray_areas[i].answered: true after each exchange.status: dialogue_active throughout.Conductor synthesizes the Brief from intent + dialogue, formats per the Brief template
in content/references/planning-artifacts.md §Brief template, and includes the Outcome rubric field:
docs/overview/_proposed/outcome-rubric.md exists (product-discovery ran before /ds-brief): copy its lines verbatim into the rubric field and note "copied from discovery draft - confirm or adjust."verification_type: deterministic if a gate is nameable, judgment otherwise. Present the assigned types for confirmation before writing.The outcome rubric is part of the Brief draft and subject to the same iteration rounds (max 3 adjustments). Store the confirmed rubric in brief-session.json under the rubric array (see Section 8).
Conductor presents the full Brief to the operator:
"Here's the Brief draft. Review it and say 'looks good' to write it, or tell me what to adjust:
Brief:
..."
Write status: draft_presented.
Operator may request changes. Conductor adjusts. Max 3 adjustment rounds; on the 4th:
"We've revised several times - do you want to keep discussing or finalize what we have?"
Write status: iterating during revision rounds.
docs/planning/<slug>.md per the template.brief-session.json status: complete, brief_path, brief_source: operator.git add docs/planning/<slug>.md
git commit -m "docs(brief): add <slug> brief"
TRACKER != none AND ticket_driven active (per resolution rule in content/sections/02-delegation.md §Ticket-offer gate): derive TICKET_TITLE from the Brief's Feature Name, TICKET_BODY from Problem + Success criteria, TICKET_TYPE from the Brief type (default feature); then:
offer mode: emit Creating ticket for this work - reply STOP to skip and proceed ad-hoc. Wait one turn. If no STOP: invoke the Tracker Create Helper (cross-ref content/commands/ds-implement-ticket.md §Tracker Create Helper). If STOP: skip creation, proceed ad-hoc (architect spawn, step 6).require mode: invoke the Tracker Create Helper immediately (no skip path)./ds-implement-ticket <CREATED_TICKET_ID> with brief_path in the execution contract INSTEAD of spawning the architect directly (skip steps 5-6).offer mode proceed ad-hoc (architect spawn, step 6); in require mode STOP and wait for operator resolution.offer mode): emit the skip line and proceed ad-hoc (architect spawn, step 6).require mode): surface the conflict (ticket_driven=require but tracker '<type>' has no create integration - proceed ad-hoc this once, or stop?) and WAIT for operator."Brief written to docs/planning/.md and committed. Spawning architect with brief_path - reply STOP to halt or refine the Brief first."
brief_path in execution contract.When the conductor identifies a dimension exceeding stated intent, surface it as a gray area rather than adding it silently:
"This sounds like it might go beyond [original intent]. I'll add '[new dimension]' to the deferred list for now - flag it if it belongs in scope."
Add the item to the deferred array with reason: scope-creep-candidate.
Conductor: "Got it - I'll fold this in."
deferred (set entry status: withdrawn).answered: false.When a new dimension materially changes the original intent:
"This sounds like a pivot - want to restart the Brief with the new framing? (restart / continue with both)"
brief-session.json, re-announce, begin from Turn 1.Invocation: /ds-brief --from <path> where path is relative or absolute.
Scan for headings or labels matching: Problem / Goals / Non-goals / Constraints / Verification (or equivalents: Objective, Acceptance Criteria, Out of Scope, Success Metrics, Definition of Done). Map matching content to Brief fields.
Also scan for headings matching: Definition of Done / Acceptance Criteria / Success Metrics / Pass-Fail / Rubric. Extract matching items as outcome rubric candidates - assign verification_type: deterministic when the item names a measurable gate, verification_type: judgment otherwise. Cap at 6 lines. If none of these headings exist, pre-fill the Outcome rubric field with [extracted from PRD - review required] and prompt: "I could not find explicit acceptance criteria in this PRD. List the 3-6 things that would make this 'done', one per line."
[extracted from PRD - review required].[REQUIRES OPERATOR INPUT - cannot proceed without verification gate]."Auto-extraction was minimal - this PRD doesn't have structural headings I can map to Brief fields. I've put the full content in Problem; you need to fill in Verification before we can proceed (Brief cannot ship without it). Want to discuss the gray areas now or just edit the draft?"
Verification field is always required. A Brief with [REQUIRES OPERATOR INPUT] in
Verification is NOT Skeptic-eligible. The conductor must collect a real Verification
value before writing the Brief to disk.
Conductor reads brief-session.json brief_source field.
brief_source: operator (Brief from /ds-brief dialogue)"Verify completeness only: all 6 fields present, Verification field is non-empty and not 'cannot specify', no Open Questions remaining (a non-empty "Deferred defaults" section does not count as unresolved Open Questions - those do not block). The problem framing and success criteria have already been operator-confirmed in the /ds-brief session - DO NOT relitigate framing decisions. Major findings are limited to: missing field, empty Verification, unresolved Open Questions, or contradictions between Brief fields. Out of scope: framing critique, alternative solutions, scope arguments."
brief_source: conductor (auto-authored at gate, no /ds-brief session)Use the standard "Document synthesis, architecture, and planning" adversarial brief. Full framing review is in scope.
Runs after intent capture, before the gray-area menu.
MEMORY.md: already in context (via the @MEMORY.md import in the project root CLAUDE.md). NO file read.
Scan in-context content for keyword overlap with intent (substring match on
space-separated keywords from the intent statement).
docs/planning/: Glob *.md at top level only (or Bash find docs/planning -maxdepth 1 -name '*.md' when Glob is unavailable), NOT subdirectories. Use filenames
only (directory listing). Match by slug-name keyword similarity (substring match).
Read AT MOST the first 20 lines of the top 3 closest-matching files.
If no matches, skip reads entirely.
Volume cap: if docs/planning/ has more than 50 .md entries at top level, restrict
to the 10 most recently modified by mtime before keyword matching.
Silent on no match.
.agentic/brief-session.jsonGitignored under the existing .agentic/ rule. No .gitignore change needed.
{
"schema_version": 1,
"status": "<see enum>",
"topic": "<intent statement>",
"slug": "<kebab-case-feature-name>",
"worktree_path": null,
"brief_path": "<docs/planning/<slug>.md or null>",
"brief_source": "<operator | conductor>",
"created_at": "<ISO8601>",
"updated_at": "<ISO8601>",
"gray_areas": [
{"id": 1, "text": "<text>", "selected": true, "answered": false}
],
"dialogue_log": [
{
"gray_area_id": 1,
"question": "<question text>",
"answer": "<operator answer>",
"followup_question": "<string or null>",
"followup_answer": "<string or null>",
"timestamp": "<ISO8601>"
}
],
"deferred": [
{
"text": "<item>",
"reason": "<scope-creep-candidate | operator-choice>",
"status": "<active | withdrawn>"
}
],
"draft": {
"problem": "<string or null>",
"success_criteria": ["<string>"],
"non_goals": ["<string>"],
"constraints": "<string or null>",
"verification": "<string or null>"
},
"rubric": [
{
"id": 1,
"line": "<one-line observable acceptance criterion>",
"verification_type": "<deterministic | judgment>",
"confirmed": false
}
]
}
intent_captured | menu_presented | dialogue_active | draft_presented | iterating | complete | interrupted
slug: kebab-case slug derived from the operator's intent statement per the slug-derivation
algorithm in Section 3 - Slug derivation. Must match the slug used by implement-ticket.md
Phase 0b for the same intent.worktree_path: reserved for future use; currently null. The conductor works directly on its current branch - no worktree is created by /ds-brief.gray_areas[].selected: bool - true if operator chose this area in the menu-selection
step; false if deferred or skipped. Conductor only walks through areas where
selected: true.brief_source drives Skeptic variant selection per Section 6.deferred[].status: withdrawn marks items the operator pushed back and folded in scope.