agentleFS
clay-goodclay-good/spec-gen/skills/openlore-brainstorm/SKILL.md

openlore-brainstorm

Skill359 starsChanged 6 months agoMITView on GitHub

Transform a feature idea into an annotated story using a Domain Sketch or Constrained Option Tree. Use when asked to brainstorm, explore, or shape a feature before implementation.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 11 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If .claude/antipatterns.md exists, read it and store as $ANTIPATTERNS.

    line 46
  2. Very specific:

    Call the openlore MCP tool get_architecture_overview with {"directory": "$PROJECT_ROOT"}.

    line 57
  3. Very specific:

    Call the openlore MCP tool generate_change_proposal with:

    line 63
  4. Distinctive:

    Do not continue until the user accepts the refactor story or explicitly overrides.

    line 92
  5. Distinctive:

    Ask: "Are there additional constraints before we explore approaches?"

    line 115
  6. Very specific:

    If $ANTIPATTERNS ≠ none, cross-check each option against the list.

    line 122
  7. Distinctive:

    Do not proceed to Step 5e until the user chooses.

    line 143
  8. Distinctive:

    Before writing the story, switch roles: challenge the chosen option as a skeptic.

    line 148
  9. Very specific:

    Only proceed to Step 6 once the user has acknowledged the failure modes.

    line 162
  10. Very specific:

    Ask: "What is explicitly out of scope for this story?" List the answers as $WONT_DO.

    line 170
  11. Distinctive:

    No existing structure to constrain — the method builds the structure from scratch.

    line 176
  12. Distinctive:

    Ask the user: "What are the core data objects this feature creates or transforms?"

    line 180
  13. Distinctive:

    Ask the user to confirm or override each decision before proceeding to Step 6.

    line 222
  14. Very specific:

    If a story template exists at $PROJECT_ROOT/_bmad/openlore/templates/story.md or $PROJECT_ROOT/examples/bmad/templates/story.md, use it.

    line 232
  15. Distinctive:

    Do not ask design questions before Step 5 (both modes)

    line 342
  16. Distinctive:

    Do not propose implementation steps — this skill ends at story creation

    line 346
  17. Distinctive:

    Every AC must be verifiable by a test — reject vague ACs ("should work", "handles errors") and rewrite them before proceeding

    line 347
  18. Distinctive:

    Delete it if this idea is not pursued."

    line 352

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

openlore: Brainstorm

When to use this skill

Trigger this skill when the user wants to explore or design a new feature before writing any code, with phrasings like:

  • "I want to add feature X"
  • "how should I approach this?"
  • "let's brainstorm this story"
  • explicit command /openlore-brainstorm

Step 1 — Detect mode

Capture $PROJECT_ROOT, $FEATURE_DESCRIPTION, and $FEATURE_SLUG (kebab-case, ≤ 5 words, e.g. payment-retry-flow).

Then probe the structural index by calling the openlore MCP tool orient with:

{
  "directory": "$PROJECT_ROOT",
  "task": "$FEATURE_DESCRIPTION",
  "limit": 7
}

Set $MODE based on the result:

Result$MODEMeaning
Returns functions with score > 0brownfieldExisting indexed codebase
Returns "error": "no cache" or 0 functionsgreenfieldNo structural index yet

Inform the user:

  • Brownfield: "I found existing code related to this feature. Using structural analysis to guide design."
  • Greenfield: "No structural index found. Using Domain Sketch — structural analysis will be available after openlore analyze is run on the first implementation."

Load project antipatterns (both modes):

If .claude/antipatterns.md exists, read it and store as $ANTIPATTERNS. These will be used as a failure mode source in Step 5. If absent, $ANTIPATTERNS = none.


Steps 2–4 — Structural analysis (brownfield only)

Skip to Step 5 if $MODE = greenfield.

Step 2 — Architecture overview

Call the openlore MCP tool get_architecture_overview with {"directory": "$PROJECT_ROOT"}.

Note hub functions and cross-domain dependencies in $DOMAINS_AFFECTED.

Step 3 — Generate change proposal

Call the openlore MCP tool generate_change_proposal with:

{
  "directory": "$PROJECT_ROOT",
  "description": "$FEATURE_DESCRIPTION",
  "slug": "$FEATURE_SLUG"
}

This chains orient + search_specs + analyze_impact and writes openspec/changes/$FEATURE_SLUG/proposal.md.

Extract:

  • $MAX_RISK_SCORE — overall risk level
  • $REQUIREMENTS_TOUCHED — existing requirements this feature overlaps
  • $BLOCKING_REFACTORS — functions with risk ≥ 70

Step 4 — Risk gate

ScoreAction
🟢 < 40Proceed to Step 5
🟡 40–69Proceed, flag impacted callers to protect during design
🔴 ≥ 70Stop — propose a blocking refactor story before continuing

If blocked:

"This feature touches $BLOCKING_FUNCTION (risk score: $SCORE). A refactor story must be completed first. I can create it now if you'd like."

Do not continue until the user accepts the refactor story or explicitly overrides.


Step 5 — Brainstorming

If $MODE = brownfield — Constrained Option Tree

5a — Establish the constraint space

Derive from Steps 2–4 and present before generating options:

Hard constraints (non-negotiable):
  - Functions with riskScore ≥ 70: $BLOCKED_FUNCTIONS
  - Requirements that must be preserved: $REQUIREMENTS_TOUCHED
  - Domain boundaries that must not be crossed: $DOMAIN_BOUNDARIES

Soft constraints (preferred):
  - Existing insertion points: $INSERTION_POINTS
  - Patterns already used in $DOMAINS_AFFECTED

Ask: "Are there additional constraints before we explore approaches?"

5b — Generate 2–3 options

Each option must respect hard constraints. Name them clearly (e.g. Option A — Extend existing, Option B — New service, Option C — Facade).

If $ANTIPATTERNS ≠ none, cross-check each option against the list. Flag any option that would reproduce a known failure pattern with ⚠ and the relevant AP-NNN.

Option AOption BOption C
Insertion point
Domains touched
Risk score impact
Requirements affected
Estimated scope (files)
Trade-off

5c — Recommend

State one recommendation with a single structural reason:

"Recommend Option B — inserts at $SAFE_FUNCTION (risk 18), avoids $HUB (fan-in 14) entirely. Option A is valid but adds unnecessary blast radius."

5d — Confirm

Do not proceed to Step 5e until the user chooses. If they want a hybrid, produce a revised option table.

5e — Adversarial challenge

Before writing the story, switch roles: challenge the chosen option as a skeptic.

State exactly 2 failure modes grounded in the structural data and, if $ANTIPATTERNS ≠ none, any applicable antipatterns from .claude/antipatterns.md:

"Devil's advocate on Option B:

  1. $CALLER_A calls $INSERTION_POINT with $EDGE_CASE — this path is not covered by the proposed approach and could silently break.
  2. The proposal scores risk at $SCORE but $HUB (fan-in $N) is one hop away — a regression there would not be caught until check_spec_drift."

Then ask the user: "Do these failure modes change your choice, or should we add mitigations to the story constraints?"

Only proceed to Step 6 once the user has acknowledged the failure modes. Mitigations go into ## Technical Constraints in the story.

Note: this IS a gate (waits for user input) because brainstorm is a design phase where changing course is cheap. In contrast, openlore-implement-story Step 4b is a mandatory self-check that does NOT gate — because by implementation time the design decision is already made.

Ask: "What is explicitly out of scope for this story?" List the answers as $WONT_DO.


If $MODE = greenfield — Domain Sketch

No existing structure to constrain — the method builds the structure from scratch.

5a — Entities

Ask the user: "What are the core data objects this feature creates or transforms?"

List them as nouns with a one-line definition each:

$ENTITY_1 — definition
$ENTITY_2 — definition

5b — Operations

For each entity, identify the operations the feature needs (create, read, transform, delete, emit, receive…):

$ENTITY_1: $OP_1, $OP_2
$ENTITY_2: $OP_1

Identify which operations cross a system boundary (external API, database, event bus, CLI…) — these are the riskiest integration points.

5c — Boundaries

Define where the feature sits relative to the system:

Entry point:   $HOW_IT_IS_TRIGGERED (HTTP request / CLI command / event / cron)
Data in:       $INPUT_FORMAT
Data out:      $OUTPUT_FORMAT or side-effects
External deps: $THIRD_PARTY_SERVICES or "none"

5d — Architecture decisions

State 2–3 decisions that must be made before coding. For each, list the options and a recommendation:

DecisionOptionsRecommendation
e.g. Storagein-memory / DB / fileDB — survives restarts
e.g. Couplingnew module / extend existingnew module — clear boundary

Ask the user to confirm or override each decision before proceeding to Step 6.

Ask: "What is explicitly out of scope for this story?" List the answers as $WONT_DO.


Step 6 — Write the story

Produce a story file at $STORIES_DIR/$FEATURE_SLUG.md.

If a story template exists at $PROJECT_ROOT/_bmad/openlore/templates/story.md or $PROJECT_ROOT/examples/bmad/templates/story.md, use it. Otherwise:

Brownfield template:

# $STORY_TITLE

## Goal

$FEATURE_DESCRIPTION

## Acceptance Criteria

Each AC must be verifiable by a test. State the observable outcome, not the intent.
✗ "Should handle errors correctly" — ✓ "Returns HTTP 400 with `{error: 'X'}` when Y is absent"

- [ ] $AC_1
- [ ] $AC_2

## Won't Do

- $WONT_DO_1
- $WONT_DO_2

## Risk Context

<!-- Filled by annotate_story in Step 7 -->

## Technical Constraints

$BLOCKING_REFACTORS and caller protection notes from the proposal.

## Notes

- Chosen approach: $CHOSEN_OPTION — $TRADE_OFF
- Domains affected: $DOMAINS_AFFECTED
- Requirements touched: $REQUIREMENTS_TOUCHED
- Max risk score: $MAX_RISK_SCORE

Greenfield template:

# $STORY_TITLE

## Goal

$FEATURE_DESCRIPTION

## Acceptance Criteria

Each AC must be verifiable by a test. State the observable outcome, not the intent.
✗ "Should handle errors correctly" — ✓ "Returns HTTP 400 with `{error: 'X'}` when Y is absent"

- [ ] $AC_1
- [ ] $AC_2

## Won't Do

- $WONT_DO_1
- $WONT_DO_2

## Domain Sketch

### Entities
$ENTITIES

### Operations
$OPERATIONS

### Boundaries
$BOUNDARIES

## Architecture Decisions

$DECISIONS_TABLE

## Notes

- First implementation — run `openlore analyze && openlore generate` after
  to enable structural analysis for future stories.

Step 7 — Annotate the story

Brownfield only. Skip if $MODE = greenfield.

Call the openlore MCP tool annotate_story with:

{
  "directory": "$PROJECT_ROOT",
  "storyFilePath": "$STORY_FILE_PATH",
  "description": "$STORY_TITLE"
}

Patches ## Risk Context directly. Story is now ready for openlore-implement-story.

Greenfield: confirm to the user:

"Story written to $STORY_FILE_PATH. No risk context yet — run openlore analyze after the first implementation sprint to enable structural analysis for future stories."


Absolute constraints

  • Do not ask design questions before Step 5 (both modes)
  • Brownfield: do not proceed past Step 4 if $MAX_RISK_SCORE ≥ 70 without acknowledgement
  • Brownfield: do not fill ## Risk Context manually — always use annotate_story
  • Greenfield: do not call annotate_story — there is nothing to annotate yet
  • Do not propose implementation steps — this skill ends at story creation
  • Every AC must be verifiable by a test — reject vague ACs ("should work", "handles errors") and rewrite them before proceeding
  • ## Won't Do is mandatory in the story — at minimum one item
  • Brownfield: generate_change_proposal creates openspec/changes/$FEATURE_SLUG/proposal.md on disk. Inform the user at session end: "A proposal file was created at openspec/changes/$FEATURE_SLUG/proposal.md. Delete it if this idea is not pursued."

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.