npm - olympus-ai - Versions diffs - 4.4.11 → 4.4.13 - Mend

olympus-ai 4.4.11 → 4.4.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/.claude-plugin/plugin.json +1 -1
package/dist/installer/index.d.ts +1 -1
package/dist/installer/index.js +1 -1
package/package.json +1 -1
package/resources/rules/common/content-validation.md +1 -26
package/resources/rules/common/markdown-formatting.md +170 -0
package/resources/rules/core-workflow.md +1 -0
package/resources/rules/inception/requirements-analysis.md +3 -1
package/resources/skills/brief/SKILL.md +73 -51
package/resources/skills/brief/templates/ai-dlc-intent-brief-template.md +149 -0
package/resources/skills/plan/SKILL.md +14 -4

package/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "olympus-ai",
-  "version": "4.4.11",
+  "version": "4.4.13",
   "description": "Olympus: Multi-agent orchestration for Claude Code. Summon the gods of code.",
   "author": {
     "name": "mikev10",

package/dist/installer/index.d.ts CHANGED Viewed

@@ -24,7 +24,7 @@ export declare const HOOKS_DIR: string;
 export declare const SETTINGS_FILE: string;
 export declare const VERSION_FILE: string;
 /** Current version - MUST match package.json */
-export declare const VERSION = "4.4.11";
+export declare const VERSION = "4.4.13";
 /** Installation result */
 export interface InstallResult {
     success: boolean;

package/dist/installer/index.js CHANGED Viewed

@@ -40,7 +40,7 @@ export const HOOKS_DIR = join(CLAUDE_CONFIG_DIR, 'hooks');
 export const SETTINGS_FILE = join(CLAUDE_CONFIG_DIR, 'settings.json');
 export const VERSION_FILE = join(CLAUDE_CONFIG_DIR, '.olympus-version.json');
 /** Current version - MUST match package.json */
-export const VERSION = '4.4.11';
+export const VERSION = '4.4.13';
 /**
  * Read a content file from the resources/ directory.
  *

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "olympus-ai",
-  "version": "4.4.11",
+  "version": "4.4.13",
   "description": "Olympus: Multi-agent orchestration for Claude Code. Summon the gods of code.",
   "type": "module",
   "main": "dist/index.js",

package/resources/rules/common/content-validation.md CHANGED Viewed

@@ -56,32 +56,7 @@ Phase 1: INCEPTION
 ## Markdown Formatting Standards
-**MANDATORY**: All generated markdown files MUST follow these formatting rules to produce clean, linter-friendly output.
-### Document Structure (MD025)
-- **One H1 per document**: Use a single `#` heading as the document title. All other sections use `##` or lower.
-- YAML frontmatter `---` does NOT count as an H1. The first `#` heading after frontmatter is the title.
-- Exception: If a document has YAML frontmatter with a `title:` field, you may omit the H1 entirely.
-### Blank Lines Around Block Elements (MD022, MD031, MD032)
-- **Headings**: Always leave one blank line BEFORE and AFTER every heading (`#`, `##`, `###`, etc.).
-- **Lists**: Always leave one blank line BEFORE and AFTER a list block (both ordered and unordered).
-- **Fenced code blocks**: Always leave one blank line BEFORE and AFTER fenced code blocks.
-- **Block quotes**: Always leave one blank line BEFORE and AFTER block quotes (`>`).
-### Whitespace Rules (MD009, MD047, MD012)
-- **No trailing spaces**: Lines must not end with trailing whitespace. Use `<br>` for intentional line breaks.
-- **File ending**: Every file must end with exactly one newline character.
-- **No consecutive blank lines**: Use at most one blank line between elements (no double blanks).
-### List Formatting (MD004, MD007, MD030)
-- **Consistent markers**: Use `-` for unordered lists (not `*` or `+`).
-- **Indentation**: Use 2 spaces for nested list indentation.
-- **Ordered list spacing**: Use `1.` followed by a single space.
+**MANDATORY**: Load and follow `common/markdown-formatting.md` for the complete markdownlint rule set and project-specific overrides. That file is the authoritative reference for all markdown formatting requirements.
 ## General Content Validation

package/resources/rules/common/markdown-formatting.md ADDED Viewed

@@ -0,0 +1,170 @@
+# Markdown Formatting Standards
+## MANDATORY: All Generated Markdown Must Pass markdownlint
+**CRITICAL**: Every markdown file you create or modify MUST comply with the [markdownlint](https://github.com/DavidAnson/markdownlint) rule set (v0.40.0). The project enforces these rules via `.markdownlint.json` at the workspace root. Violations will cause linter failures on save.
+## Project Configuration Overrides
+The project `.markdownlint.json` modifies the defaults as follows. **Always respect these overrides:**
+| Setting       | Value                                                                | Effect                                                                                        |
+|---------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
+| `default`     | `true`                                                               | All rules enabled unless explicitly disabled                                                  |
+| `frontMatter` | `"^---\s*$[\s\S]*?^---\s*$"`                                         | YAML frontmatter blocks are recognized and excluded from rules                                |
+| `MD013`       | `false`                                                              | **Line length is NOT enforced** — no maximum line width                                       |
+| `MD024`       | `{ "siblings_only": true }`                                          | Duplicate headings allowed if they are NOT siblings (same parent)                             |
+| `MD033`       | `{ "allowed_elements": ["br", "details", "summary", "sup", "sub"] }` | Inline HTML forbidden EXCEPT these five elements                                              |
+| `MD036`       | `false`                                                              | **Emphasis-as-heading is allowed** — bold text may serve as pseudo-headings                   |
+| `MD041`       | `false`                                                              | **First line need not be an H1** — files may start with frontmatter, badges, or other content |
+## Editor Integration
+The project `.vscode/settings.json` configures:
+- **markdownlint runs on save** — violations are flagged immediately
+- **Format on save** enabled with `markdown-table-prettify` as the default formatter
+- **Word wrap off** — lines are not soft-wrapped in the editor
+When generating tables, produce clean pipe-aligned tables since the prettifier will reformat them on save.
+---
+## Rule Reference
+All 54 active markdownlint rules organized by category. Rules disabled by project config are marked with **(DISABLED)**.
+### Document Structure
+| Rule  | Alias                     | Requirement                                                            |
+|-------|---------------------------|------------------------------------------------------------------------|
+| MD001 | `heading-increment`       | Heading levels must increment by one (no skipping H2 to H4)            |
+| MD025 | `single-h1`               | Only one H1 (`#`) per document. YAML frontmatter `title:` counts as H1 |
+| MD041 | `first-line-h1`           | **(DISABLED)** First line need not be a top-level heading              |
+| MD043 | `required-headings`       | Required heading structure if configured (default: not configured)     |
+| MD047 | `single-trailing-newline` | File MUST end with exactly one newline character                       |
+### Headings
+| Rule  | Alias                          | Requirement                                                                                    |
+|-------|--------------------------------|------------------------------------------------------------------------------------------------|
+| MD003 | `heading-style`                | Use consistent heading style — use ATX style (`# Heading`) throughout                          |
+| MD018 | `no-missing-space-atx`         | Must have a space after `#` in headings: `# Heading` not `#Heading`                            |
+| MD019 | `no-multiple-space-atx`        | Only one space after `#`: `# Heading` not `#  Heading`                                         |
+| MD020 | `no-missing-space-closed-atx`  | Closed ATX headings need inner spaces: `# Heading #`                                           |
+| MD021 | `no-multiple-space-closed-atx` | Only one space inside closed ATX hashes                                                        |
+| MD022 | `blanks-around-headings`       | One blank line BEFORE and AFTER every heading                                                  |
+| MD023 | `heading-start-left`           | Headings must start at column 1 (no indentation)                                               |
+| MD024 | `no-duplicate-heading`         | No duplicate heading text among **siblings** (same-parent headings may repeat across sections) |
+| MD026 | `no-trailing-punctuation`      | Headings must not end with `.` `,` `;` `:` `!` or their CJK equivalents                        |
+| MD036 | `no-emphasis-as-heading`       | **(DISABLED)** Bold/italic text may be used as pseudo-headings                                 |
+### Lists
+| Rule  | Alias                 | Requirement                                                                    |
+|-------|-----------------------|--------------------------------------------------------------------------------|
+| MD004 | `ul-style`            | Use consistent unordered list markers — use `-` (dash) for all unordered lists |
+| MD005 | `list-indent`         | Sibling list items must have consistent indentation                            |
+| MD007 | `ul-indent`           | Indent nested unordered list items by **2 spaces**                             |
+| MD029 | `ol-prefix`           | Ordered lists: use `1.` for all items OR sequential numbering — be consistent  |
+| MD030 | `list-marker-space`   | Exactly one space after list markers (`-`, `1.`)                               |
+| MD032 | `blanks-around-lists` | One blank line BEFORE and AFTER every list block                               |
+### Code Blocks and Fences
+| Rule  | Alias                  | Requirement                                                |
+|-------|------------------------|------------------------------------------------------------|
+| MD010 | `no-hard-tabs`         | No tab characters — use spaces only                        |
+| MD014 | `commands-show-output` | Don't prefix commands with `$` unless showing output below |
+| MD031 | `blanks-around-fences` | One blank line BEFORE and AFTER every fenced code block    |
+| MD040 | `fenced-code-language` | Fenced code blocks MUST specify a language (e.g., ` ```typescript `)            |
+| MD046 | `code-block-style`     | Use consistent code block style — use **fenced** (backtick) style, not indented |
+| MD048 | `code-fence-style`     | Use consistent fence delimiters — use **backticks** (`` ` ``), not tildes (`~`) |
+### Whitespace and Formatting
+| Rule  | Alias                  | Requirement                                                                            |
+|-------|------------------------|----------------------------------------------------------------------------------------|
+| MD009 | `no-trailing-spaces`   | No trailing whitespace at end of lines. Use `<br>` for intentional line breaks         |
+| MD012 | `no-multiple-blanks`   | Maximum one consecutive blank line between elements                                    |
+| MD013 | `line-length`          | **(DISABLED)** No maximum line length enforced                                         |
+| MD035 | `hr-style`             | Use consistent horizontal rules — use `---`                                            |
+| MD037 | `no-space-in-emphasis` | No spaces inside emphasis: `**bold**` not `** bold **`                                 |
+| MD038 | `no-space-in-code`     | No leading/trailing spaces inside backtick code spans: `` `code` `` not `` ` code ` `` |
+| MD049 | `emphasis-style`       | Use consistent emphasis markers — use `*` (asterisk) for italics                       |
+| MD050 | `strong-style`         | Use consistent strong markers — use `**` (double asterisk) for bold                    |
+### Links and Images
+| Rule  | Alias                              | Requirement                                                               |
+|-------|------------------------------------|---------------------------------------------------------------------------|
+| MD011 | `no-reversed-links`                | Correct link syntax: `[text](url)` not `(text)[url]`                      |
+| MD034 | `no-bare-urls`                     | URLs must be wrapped: `<https://example.com>` or `[text](url)` — not bare |
+| MD039 | `no-space-in-links`                | No spaces inside link brackets: `[text](url)` not `[ text ](url)`         |
+| MD042 | `no-empty-links`                   | Links must have a non-empty destination                                   |
+| MD044 | `proper-names`                     | Proper names must use correct capitalization if configured                |
+| MD045 | `no-alt-text`                      | Images MUST have alt text: `![description](image.png)`                    |
+| MD051 | `link-fragments`                   | Link fragment anchors (`#section`) must reference valid headings          |
+| MD052 | `reference-links-images`           | Reference-style links must use defined labels                             |
+| MD053 | `link-image-reference-definitions` | Reference definitions must be used (no orphaned definitions)              |
+| MD054 | `link-image-style`                 | Use consistent link style (inline, reference, etc.)                       |
+| MD059 | `descriptive-link-text`            | Avoid generic link text like "click here", "here", "link", "more"         |
+### Blockquotes
+| Rule  | Alias                          | Requirement                                             |
+|-------|--------------------------------|---------------------------------------------------------|
+| MD027 | `no-multiple-space-blockquote` | Only one space after `>`: `> text` not `>  text`        |
+| MD028 | `no-blanks-blockquote`         | No blank lines inside a blockquote (splits it into two) |
+### Tables
+| Rule  | Alias                  | Requirement                                                    |
+|-------|------------------------|----------------------------------------------------------------|
+| MD055 | `table-pipe-style`     | Use consistent pipe style — include leading and trailing pipes |
+| MD056 | `table-column-count`   | All rows must have the same number of columns                  |
+| MD058 | `blanks-around-tables` | One blank line BEFORE and AFTER every table                    |
+| MD060 | `table-column-style`   | Use consistent column alignment syntax in delimiter rows       |
+### Inline HTML
+| Rule  | Alias            | Requirement                                                                             |
+|-------|------------------|-----------------------------------------------------------------------------------------|
+| MD033 | `no-inline-html` | Inline HTML is **forbidden** except: `<br>`, `<details>`, `<summary>`, `<sup>`, `<sub>` |
+---
+## Quick Reference: Most Common Violations
+When generating markdown, watch for these frequent issues:
+1. **Missing blank lines** (MD022, MD031, MD032, MD058) — Always surround headings, code blocks, lists, and tables with blank lines
+2. **Trailing whitespace** (MD009) — Strip trailing spaces from every line
+3. **No language on code fences** (MD040) — Always specify a language: use `text` or `markdown` when no syntax applies
+4. **Multiple H1 headings** (MD025) — Only one `#` per file; use `##` and below for sections
+5. **Inconsistent list markers** (MD004) — Always use `-` for unordered lists
+6. **Bare URLs** (MD034) — Wrap URLs in angle brackets or make them proper links
+7. **Missing final newline** (MD047) — Files must end with exactly one `\n`
+8. **Heading level skips** (MD001) — Go `#` then `##` then `###` — never skip levels
+9. **Missing image alt text** (MD045) — Every `![](image)` needs descriptive alt text
+10. **Spaces inside emphasis/code** (MD037, MD038) — No spaces inside `**`, `*`, or backticks
+## Pre-Write Validation Checklist
+Before writing ANY markdown file, verify:
+- [ ] Single `#` H1 (or none if frontmatter has `title:`)
+- [ ] Heading levels increment by one (no skips)
+- [ ] Blank lines around all block elements (headings, lists, code blocks, tables, blockquotes)
+- [ ] No trailing whitespace on any line
+- [ ] No consecutive blank lines
+- [ ] All code fences specify a language
+- [ ] Code fences use backticks, not tildes
+- [ ] Unordered lists use `-` consistently
+- [ ] List indentation uses 2 spaces
+- [ ] No bare URLs
+- [ ] All images have alt text
+- [ ] No forbidden inline HTML (only `<br>`, `<details>`, `<summary>`, `<sup>`, `<sub>` allowed)
+- [ ] File ends with exactly one newline
+- [ ] No tab characters anywhere
+- [ ] Tables have consistent column counts and pipe style

package/resources/rules/core-workflow.md CHANGED Viewed

@@ -21,6 +21,7 @@ The AI model intelligently assesses what stages are needed based on:
 - Load `~/.claude/olympus/rules/common/process-overview.md` for workflow overview
 - Load `~/.claude/olympus/rules/common/session-continuity.md` for session resumption guidance
 - Load `~/.claude/olympus/rules/common/content-validation.md` for content validation requirements
+- Load `~/.claude/olympus/rules/common/markdown-formatting.md` for markdown formatting and markdownlint compliance
 - Load `~/.claude/olympus/rules/common/question-format-guide.md` for question formatting rules
 - Load `~/.claude/olympus/rules/common/terminology.md` for phase/stage naming conventions
 - Load `~/.claude/olympus/rules/common/error-handling.md` for error recovery procedures

package/resources/rules/inception/requirements-analysis.md CHANGED Viewed

@@ -94,7 +94,7 @@ Analyze whatever the user has provided:
 **MANDATORY**: Evaluate ALL of these areas and ask questions for ANY that are unclear:
 - **Functional Requirements**: Core features, user interactions, system behaviors
 - **Non-Functional Requirements**: Performance, security, scalability, usability
-- **User Scenarios**: Use cases, user journeys, edge cases, error scenarios
+- **Scenario Coverage**: Use cases, user journeys, edge cases, error scenarios
 - **Business Context**: Goals, constraints, success criteria, stakeholder needs
 - **Technical Context**: Integration points, data requirements, system boundaries
 - **Quality Attributes**: Reliability, maintainability, testability, accessibility
@@ -188,8 +188,10 @@ When done, let me know and I will incorporate your approved findings into the re
      - Scope estimate
      - Complexity estimate
    - Include both functional and non-functional requirements
+   - Include scenario coverage when relevant (use cases, edge cases, error scenarios)
    - Incorporate user's answers to clarifying questions
    - Provide brief summary of key requirements
+   - **Do NOT include a User Stories section** — user stories with personas and acceptance criteria are generated in the dedicated User Stories stage
 ### Step 8: MANDATORY: Update State Tracking

package/resources/skills/brief/SKILL.md CHANGED Viewed

@@ -6,6 +6,10 @@ description: Generate structured intent briefs as pre-elaboration inputs for /pl
 You help teams capture the "what" and "why" before diving into the "how." Intent briefs are lightweight, structured documents that serve as high-quality inputs to `/plan` workflows and Mob Elaboration sessions. They live in `.olympus/briefs/` as pre-workflow artifacts — created before any AI-DLC workflow exists.
+## MANDATORY: Question Format
+**CRITICAL**: Load and follow `resources/rules/common/question-format-guide.md` for ALL questions. You must NEVER ask questions directly in chat. ALL questions must be placed in dedicated question files using the multiple-choice format defined in the guide.
 ## Input
 ```
@@ -21,7 +25,7 @@ Determine which mode to run based on the input:
 - **`--batch`** flag or input contains a list of items → **Batch Mode**
 - Everything else → **Single Mode**
-If the input already contains substantial context (e.g., the user pasted a feature description, a ticket, or a problem statement), extract what you can from it and confirm rather than re-asking. The goal is a conversation, not a questionnaire.
+If the input already contains substantial context (e.g., the user pasted a feature description, a ticket, or a problem statement), extract what you can and pre-fill it — then only ask questions for the gaps via question files.
 ### Thin-Context Handling
@@ -37,84 +41,96 @@ The goal is that even a thin-context brief is useful — it captures what is kno
 ## Single Mode
-### The Interview
+### Step 1: Extract Context from Input
-Have a natural conversation to understand the user's intent. You're trying to fill in these sections, but don't march through them like a checklist — let the conversation flow and ask follow-ups where it matters most.
+Before creating questions, analyze the user's input to extract everything you already know. If the input contains substantial context (a feature description, ticket, problem statement), pre-fill what you can. This reduces the number of questions the user needs to answer.
-**Core questions (ask these):**
+Capture from input:
+- Stakeholder names and their relationship to the request
+- Implicit constraints ("we're on .NET 6" or "this is a legacy iFrame")
+- Dependencies between this work and other known work
+- Urgency signals ("Mario asked for this", "blocking 3 accounts")
+- Project type signals (greenfield vs brownfield)
-1. **What needs to change?** — The problem or opportunity. What's broken, missing, or possible? Get specific enough that someone unfamiliar with the context could understand.
+### Step 2: Create the Question File
-2. **Why does it matter?** — Who's asking for this, what's the business impact, and why now? This is what separates a brief from a sticky note. If the user mentions a stakeholder request, capture the name and context.
+Create a question file following the format in `resources/rules/common/question-format-guide.md`.
-3. **What does "done" look like?** — The desired outcome, described in terms of what should be true when this work is complete. Keep it outcome-focused ("customers can self-serve password resets") not implementation-focused ("add a /reset-password endpoint").
+**File location:** `.olympus/briefs/{kebab-case-name}-questions.md`
-**Contextual questions (ask as needed — skip what's obvious or irrelevant):**
+Generate questions that map to the brief template sections. Skip questions where the input already provides a clear answer — pre-fill those into your context and note them at the top of the question file as "Pre-filled from input."
-4. **What's in scope and what's not?** — Boundaries prevent scope creep during elaboration. Especially useful when a problem could be interpreted broadly.
+**Question bank** — include all that are relevant, skip what's already known:
-5. **Known constraints?** — Technical limitations, deadlines, dependencies on other work, team availability. Anything the elaboration team should know upfront.
+1. **Intent** — "What best describes the core intent?" Frame options around: "We need to [what] so that [who] can [outcome], because today [pain point]." Push for specificity. `(select one)`
-6. **Priority relative to other work?** — Where does this sit? Is it urgent, important-but-not-urgent, or nice-to-have? If other briefs exist, how does this one rank?
+2. **Primary audience** — "Who is the primary audience for this work?" Options based on likely personas from the input. `(select one)`
-7. **Any references?** — Tickets, designs, prior art, related features, stakeholder emails. Links and pointers that give the elaboration team a head start.
+3. **Secondary audiences** — "Who else is affected by or benefits from this work?" `(select all that apply)`
-**Things to listen for and capture even if not explicitly asked:**
-- Stakeholder names and their relationship to the request
-- Implicit constraints ("we're on .NET 6" or "this is a legacy iFrame")
-- Dependencies between this work and other known work
-- Urgency signals ("Mario asked for this", "blocking 3 accounts")
+4. **Success criteria** — "What does success look like?" Directional outcomes, not precise metrics. Keep options outcome-focused, not implementation-focused. `(select all that apply)`
-### Generating the Brief
+5. **Scope signals (in scope)** — "Which capabilities are in scope?" High-level capabilities the user expects. `(select all that apply)`
-Once you have enough context, generate the brief. Don't wait for perfect information — a brief with a few "Unknown" sections is better than no brief.
+6. **Scope boundaries (out of scope)** — "What is explicitly out of scope?" Critical for preventing AI over-scoping during Inception. `(select all that apply)`
-Create the directory if needed, then write the brief:
+7. **Technical constraints** — "What technical constraints apply?" Platform, framework, database, API limitations. `(select all that apply)`
-**File location:** `.olympus/briefs/{kebab-case-name}.md`
+8. **Business/organizational constraints** — "What business or organizational constraints apply?" Team capacity, deadlines, approval gates. `(select all that apply)`
-**Template:**
+9. **Compliance/security constraints** — "What compliance or security constraints apply?" Data handling, access control, regulatory requirements. `(select all that apply)`
-```markdown
-# Intent Brief: [Name]
+10. **Project type** — "Is this a new project or existing codebase?" `(select one)`
-**Date:** [ISO date]
-**Author:** [who created it — ask if not obvious, default to "Unknown" if not provided]
-**Status:** Draft
+11. **Existing system context** — For brownfield: "What describes the current system landscape?" System architecture, integration points, known tech debt. `(select all that apply)`
-## Problem
+12. **Dependencies and risks** — "What could block this work?" `(select all that apply)`
-[Clear problem statement — what's wrong or what opportunity exists. 2-4 sentences that someone unfamiliar with the context could understand.]
+13. **Non-functional requirements** — "Which NFRs are relevant?" Performance, availability, scalability, accessibility, observability. `(select all that apply)`
-## Business Motivation
+14. **Stakeholders for Mob Elaboration** — "Who needs to be in the Mob Elaboration room?" `(select all that apply)`
-[Who wants this, why it matters, business impact. Include stakeholder names if known. Capture urgency signals.]
+15. **Open pre-inception questions** — "Are there questions that must be answered BEFORE Mob Elaboration?" `(select all that apply)`
-## Desired Outcome
+16. **Priority** — "How does this rank relative to other work?" `(select one)`
-[What "done" looks like — outcome-focused, not implementation-focused. Describe the end state, not the steps to get there.]
+**Question generation guidelines:**
+- Only include questions where the answer is NOT already clear from the input
+- For questions you do include, craft meaningful options based on what you know about the context — don't use generic filler options
+- Always include "Other" as the last option (MANDATORY per question-format-guide)
+- Always include `[Recommendation]:` with reasoning before `[Answer]:`
+- Always include selection type `(select one)` or `(select all that apply)`
-## Scope
+### Step 3: Inform User and Wait
-### In Scope
-- [Specific items this work covers]
+Tell the user the question file has been created, how many questions it contains, and where to find it. Wait for the user to confirm they've completed their answers ("done", "completed", "finished", or similar).
-### Out of Scope
-- [What this work explicitly does NOT cover — prevents scope creep during elaboration]
+### Step 4: Read, Validate, and Analyze Answers
-## Known Constraints
+1. Read the question file
+2. Extract answers after `[Answer]:` tags
+3. Validate all questions are answered — if any are empty, ask the user to complete them
+4. Check for contradictions and ambiguities per the question-format-guide
+5. If contradictions found, create a clarification file at `.olympus/briefs/{kebab-case-name}-clarification-questions.md` and wait for resolution
-- [Technical, timeline, dependency, or team constraints]
-- [Include anything that would surprise the elaboration team if they didn't know it upfront]
+### Step 5: Generate the Brief
-## References
+Once all answers are validated and contradictions resolved, generate the brief.
+Create the directory if needed, then write the brief:
-- [Links to tickets, designs, prior art, stakeholder communications]
+**File location:** `.olympus/briefs/{kebab-case-name}.md`
-## Notes for Elaboration
+**Template:** Read and use the template at `resources/skills/brief/templates/ai-dlc-intent-brief-template.md`. Fill in each section based on the user's answers and any context extracted in Step 1. For sections where you have no information:
+- Replace placeholder text with "Unknown" followed by the specific questions that would need to be answered
+- For tables, keep the header row and add a single row with "Unknown — [what needs to be determined]"
+- Remove the instructional italics and example text, replacing them with actual content
-[Anything the team should discuss during Mob Elaboration — open questions, risks you can see, areas where the team's expertise is needed to make decisions. This section is where you flag things the brief can't answer alone.]
-```
+**Metadata mapping:**
+- **Author** → from answers or "Unknown"
+- **Last Updated** → current ISO date
+- **Status** → "Draft" (always for new briefs)
+- **Project Type** → "Greenfield" or "Brownfield" based on answers
 After writing, confirm the file path and offer:
 - "Want to adjust anything before we finalize?"
@@ -134,13 +150,19 @@ Confirm the list back: "I see N items. Here's what I've got: [list]. Does this l
 ### Step 2: Lightweight Interview
-Don't run the full 7-question interview for each item — that would take forever with a large list. Instead:
+Don't run the full 16-question interview for each item — that would take forever with a large list. Instead, create a single consolidated question file.
+**File location:** `.olympus/briefs/batch-questions.md`
+Structure the question file in two parts:
+1. **Shared context questions** — things that apply to all items (e.g., stakeholder, common motivation, shared constraints, project type, compliance requirements). Ask these once.
-1. **Ask shared context questions once** — things that apply to all items (e.g., "Who's the stakeholder for all of these?", "What's the common motivation?", "Are there shared constraints?")
+2. **Per-item questions** — for each item, ask only what's unique: the intent and any item-specific context. If items are similar (e.g., "update iFrame for billing page" and "update iFrame for schedule page"), template the question structure and ask about differences.
-2. **For each item, ask only what's unique** — the problem statement and any item-specific context. If items are similar (e.g., "update iFrame for billing page" and "update iFrame for schedule page"), you can template the brief structure and ask about differences.
+3. **Infer where possible** — if the user says "Mario requested the first 5", don't ask about stakeholder for each of those 5. Note inferences at the top of the file as "Pre-filled from input."
-3. **Infer where possible** — if the user says "Mario requested the first 5", you don't need to ask about stakeholder for each of those 5.
+Follow the question-format-guide for all questions (multiple-choice, `[Recommendation]:`, `[Answer]:` tags, "Other" as last option). Inform the user, then wait for completion before proceeding.
 ### Step 3: Prioritize
@@ -157,7 +179,7 @@ If the user already has a priority order, confirm it rather than re-deriving it.
 ### Step 4: Generate All Briefs
-Write each brief to `.olympus/briefs/{kebab-case-name}.md` using the same template as single mode. Include the priority position in each brief's metadata.
+Write each brief to `.olympus/briefs/{kebab-case-name}.md` using the same template as single mode (from `resources/skills/brief/templates/ai-dlc-intent-brief-template.md`). Include the priority position in each brief's metadata.
 ### Step 5: Generate the Index

package/resources/skills/brief/templates/ai-dlc-intent-brief-template.md ADDED Viewed

@@ -0,0 +1,149 @@
+# AI-DLC Intent Brief
+**Author:** [Your name]
+**Last Updated:** [Date]
+**Status:** Draft | Ready for Mob Elaboration
+**Project Type:** Greenfield | Brownfield
+---
+## Intent
+_A clear, concise statement of what you want to build and why. This is the seed the AI decomposes during Inception. Write it the way you'd pitch the problem to a new team member in 60 seconds._
+We need to [what the system should do] so that [who benefits] can [outcome achieved], because today [current pain point or gap].
+**Example:** We need to build a consolidated reporting engine so that account managers can generate cross-account summaries in minutes instead of hours, because today they manually pull data from three separate systems and lose ~3 hours/week per person.
+---
+## Business Context
+### Who is this for?
+| Segment | Role / Persona | Why they care |
+|---------|---------------|---------------|
+| Primary | [e.g., Account managers with 5+ accounts] | [e.g., Directly impacted by manual reporting burden] |
+| Secondary | [e.g., Team leads consuming rolled-up data] | [e.g., Need accurate data for planning decisions] |
+### What does success look like?
+_Don't over-specify metrics yet — the AI will help refine these during Mob Elaboration. Capture the directional outcomes you care about._
+- [e.g., Dramatically reduce time spent on manual data pulls]
+- [e.g., Improve accuracy of cross-account reporting]
+- [e.g., High adoption within the first quarter post-launch]
+---
+## Scope Boundaries
+### Explicitly Out of Scope
+_This is the most important section for preventing AI over-scoping during Inception. Be specific about what you are NOT building._
+- [e.g., Custom report builder — planned for a future phase]
+- [e.g., Real-time streaming / live dashboards]
+- [e.g., Third-party data source integrations]
+- [e.g., Changes to the underlying data models in source systems]
+### Scope Signals (In Scope, Directional)
+_High-level capabilities you expect. The AI will decompose these into stories and units — don't write detailed requirements here._
+- [e.g., Automated aggregation across account types A, B, and C]
+- [e.g., Export functionality (CSV, PDF at minimum)]
+- [e.g., Role-based access control]
+---
+## Constraints
+_Realities the AI cannot infer. These shape the solution space before any design work begins._
+### Technical Constraints
+- [e.g., Must integrate with existing REST APIs for account types A and B]
+- [e.g., Must work within the current frontend framework — no new UI dependencies]
+- [e.g., Database is PostgreSQL 14; no migration budget in this phase]
+### Business / Organizational Constraints
+- [e.g., Engineering capacity: 2 backend + 1 frontend for this initiative]
+- [e.g., Must ship before Q3 planning cycle begins]
+- [e.g., Cannot change the existing billing data schema without Finance approval]
+### Compliance / Security Constraints
+- [e.g., Data exports must comply with SOC 2 requirements]
+- [e.g., PII must be masked in any shared or exported reports]
+- [e.g., All API endpoints require authentication via existing SSO]
+---
+## Existing System Context
+_Critical for brownfield projects. Give the AI enough to understand what it's working with._
+### System Landscape
+- [e.g., Monolithic Rails app with a React frontend, deployed on AWS ECS]
+- [e.g., Account data lives in three microservices: accounts-svc, billing-svc, usage-svc]
+- [e.g., Current reporting is a set of ad-hoc SQL queries run manually against a read replica]
+### Key Integration Points
+- [e.g., accounts-svc API (stable, documented)]
+- [e.g., billing-svc API (stable, documented)]
+- [e.g., usage-svc API (undocumented, needs a spike)]
+### Known Technical Debt or Risks
+- [e.g., usage-svc has no published API contract — will need reverse engineering]
+- [e.g., Read replica has a 15-minute replication lag]
+_For greenfield projects, replace this section with a brief note on target platform/stack if known, or mark as "To be determined during Inception."_
+---
+## Dependencies & Risks
+| Item | Type | Owner | Impact if Unresolved |
+|------|------|-------|---------------------|
+| [e.g., usage-svc API contract] | Technical | Backend team | Blocks integration work for account type C |
+| [e.g., Design resource availability] | Organizational | Design lead | Delays UI work; may need async review process |
+| [e.g., Data accuracy in source systems] | Data quality | Data team | Garbage-in/garbage-out for consolidated reports |
+---
+## Non-Functional Requirements (Known)
+_Capture NFRs you already know. The AI-DLC workflow will evaluate these and may surface additional ones during Inception._
+- **Performance:** [e.g., Report generation must complete within 30 seconds for up to 50 accounts]
+- **Availability:** [e.g., Must meet existing platform SLA of 99.9%]
+- **Scalability:** [e.g., Must support up to 200 concurrent users]
+- **Accessibility:** [e.g., Must meet WCAG 2.1 AA]
+- **Observability:** [e.g., Must integrate with existing Datadog monitoring]
+---
+## Stakeholders for Mob Elaboration
+_Who needs to be in the room when Inception kicks off?_
+| Name | Role | Why they're needed |
+|------|------|--------------------|
+| [Name] | Product Owner | Owns the intent and prioritization decisions |
+| [Name] | Engineering Lead | Technical feasibility and architecture input |
+| [Name] | QA / Test Lead | Acceptance criteria and edge case identification |
+| [Name] | Security / Compliance | Validates NFRs and compliance constraints |
+| [Name] | Ops / DevOps | Deployment and infrastructure considerations |
+---
+## Open Pre-Inception Questions
+_Things you need answered BEFORE Mob Elaboration — not questions for the AI to resolve during Inception._
+- [ ] [e.g., Has Finance signed off on the billing schema freeze?]
+- [ ] [e.g., Do we have API credentials for the usage-svc staging environment?]
+- [ ] [e.g., Is the design team available for async review during the build phase?]
+---
+_Once this brief is complete and pre-inception questions are resolved, trigger Mob Elaboration. The AI-DLC Inception phase will decompose the Intent into requirements, stories, and units — with the team validating every step._

package/resources/skills/plan/SKILL.md CHANGED Viewed

@@ -895,10 +895,19 @@ Write result to `aidlc-docs/{workflowId}/inception/prfaq.md`. If generation fail
   Task(
     subagent_type="momus",
     description="Workflow planning review",
-    prompt="Critically review this inception plan for: (1) gaps in requirements, (2) unrealistic acceptance criteria, (3) missing edge cases, (4) architectural risks, (5) incorrect depth/risk assessment. Intent: {intent.md}. Requirements: {requirements.md}. Execution plan: {execution-plan.md}."
+    prompt="Critically review this inception plan for: (1) gaps in requirements, (2) unrealistic acceptance criteria, (3) missing edge cases, (4) architectural risks, (5) incorrect depth/risk assessment. Intent: {intent.md}. Requirements: {requirements.md}. Execution plan: {execution-plan.md}. For each finding, include a clear recommendation stating whether the issue should be fixed now, deferred, or is informational only."
   )
   ```
-  Save output to `aidlc-docs/{workflowId}/inception/intent-review.md` with metadata (reviewer: momus, trigger: automatic, trust level, verdict). Present Momus feedback to the user. Address critical issues.
+  **Write findings to file**: After Momus returns, create `aidlc-docs/{workflowId}/inception/momus-review.md` with metadata (reviewer: momus, trigger: automatic, trust level, verdict) and the full review. Format each finding with:
+  - The finding description and severity (critical, important, minor)
+  - **Recommendation**: Whether to fix now (with suggested change), defer to a later stage, or note as informational — be explicit about the recommended action
+  - **Decision**: `[ ]` — empty checkbox for the user to mark with their decision
+  - **User Comments**: blank line for the user to add notes
+  Include a response guide at the top of the file explaining how to review (check findings to incorporate, add comments, or skip).
+  Do not silently incorporate or fix findings. The user must review the file and respond before any changes are made. This is a human approval gate.
 - **Trust 2+** (and not Risk Tier 3): Tell the user: "Optional: Run `/review` for Momus feedback on the inception plan."
@@ -923,12 +932,13 @@ Write result to `aidlc-docs/{workflowId}/inception/prfaq.md`. If generation fail
 - `aidlc-docs/{workflowId}/inception/plans/execution-plan.md`
 - `aidlc-docs/{workflowId}/inception/plans/workflow-routing.md`
 - `aidlc-docs/{workflowId}/inception/prfaq.md` (if generated)
-- `aidlc-docs/{workflowId}/inception/intent-review.md` (if Momus ran)
+- `aidlc-docs/{workflowId}/inception/momus-review.md` (if Momus ran)
 ### What needs your review
 - [ ] Depth assessment ({SHALLOW|MEDIUM|DEEP}, score {N}/30) is appropriate
 - [ ] Risk tier ({1|2|3}) correctly reflects implementation risk
 - [ ] Execution plan covers all required phases and stages
+- [ ] Momus review findings reviewed (if applicable) — check findings to incorporate, add comments in the file
 ---
@@ -1280,7 +1290,7 @@ Update `aidlc-docs/{workflowId}/checkpoint.json`:
 4. **CHECKPOINTS ARE MANDATORY**: Save checkpoint state after every stage transition (update inception_stages, current_inception_stage, state file, audit). This enables resume on interruption.
 5. **TRUST ADJUSTS CEREMONY**: Higher trust = fewer questions + lighter gates. Lower trust = more thorough validation.
 6. **REVIEW REQUIRED AFTER EVERY STAGE**: Use the exact REVIEW REQUIRED / WHAT'S NEXT format after each stage completes.
-7. **RESEARCH IS SILENT**: Agent research dispatches (explore, librarian) happen without announcing them to the user. Only surface findings in the artifacts. **Exception**: Metis blind spot analysis writes findings to a dedicated file for user review — do not silently incorporate.
+7. **RESEARCH IS SILENT**: Agent research dispatches (explore, librarian) happen without announcing them to the user. Only surface findings in the artifacts. **Exception**: Metis blind spot analysis and Momus review findings write to dedicated files for user review — do not silently incorporate or fix.
 8. **STATE TRACKING IS TRIPLE**: Every stage update must write to checkpoint.json + aidlc-state.md + audit.md.
 9. **RESUME IS IDEMPOTENT**: Each stage checks its `inception_stages` entry before executing. `completed` or `skipped` → skip to next. `in_progress` with `questions_file` set → resume Q&A without regenerating.