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

openlore-implement-story

Skill359 starsChanged 6 months agoMITView on GitHub

Implement a brownfield story with OpenLore orientation, risk checks, spec validation, tests, and drift detection. Use when asked to implement or continue a story in an existing codebase.

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

25 rules. About 0 are common, 10 are distinctive, and 15 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 15

    Very specific

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

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

    If orient returns "error": "no cache" → run analyze_codebase first, then retry.

    line 18
  2. Distinctive:

    Read the story file. Extract:

    line 24
  3. Very specific:

    Call the openlore MCP tool orient with:

    line 39
  4. Very specific:

    If riskLevel is "high" or any callee is external, check the cluster:

    line 63
  5. Very specific:

    Do not implement. Run /openlore-execute-refactor on the blocking function first, or create a blocking refactor task and return to this …

    line 86
  6. Very specific:

    Call whichever openlore MCP inventory tool applies, e.g.

    line 102
  7. Distinctive:

    Use the results to ground the implementation in existing schemas/routes — the plan cannot contradict what already exists.

    line 104
  8. Distinctive:

    If relevant requirements are found, read the domain spec before writing any code.

    line 138
  9. Very specific:

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

    line 145
  10. Very specific:

    Run the openlore-repair host skill before implementing.

    line 149
  11. Distinctive:

    If both are clean, continue to Step 4 without action.

    line 155
  12. Very specific:

    Use insertion_points from risk_context if present.

    line 161
  13. Very specific:

    Read the skeleton of the target file by calling the openlore MCP tool get_function_skeleton with:

    line 172
  14. Very specific:

    Before writing any code, state explicitly what could break with this approach.

    line 184
  15. Very specific:

    If .claude/antipatterns.md exists, read it and include any applicable patterns.

    line 185
  16. Very specific:

    Before editing, call record_decision when the chosen approach establishes a module boundary, interface contract, dependency, non-obvious …

    line 198
  17. Very specific:

    Do not touch functions outside the scope identified in Step 2 / risk_context without re-running the gate.

    line 212
  18. Distinctive:

    Small model constraint: if the model is under 13B parameters, each edit must touch a contiguous block of at most 50 lines.

    line 215
  19. Distinctive:

    Run the full test suite. If any pre-existing test breaks, fix the regression before continuing.

    line 224
  20. Distinctive:

    Write a test that directly exercises the behaviour described in the acceptance criterion.

    line 227
  21. Distinctive:

    Only run once tests are green.

    line 240
  22. Distinctive:

    Do not write code before Step 4 confirmation

    line 255
  23. Very specific:

    If riskScore ≥ 70 — stop, do not work around it, run /openlore-execute-refactor first

    line 256
  24. Very specific:

    Do not run check_spec_drift before tests are green

    line 257
  25. Distinctive:

    Do not propose a spec update on untested code

    line 258

≈ “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: Implement Story

When to use this skill

Trigger this skill when the user asks to implement a story or task on a codebase that has openlore analysis available, with phrasings like:

  • "implement story X"
  • "work on task Y"
  • "start implementing this feature"
  • explicit command /openlore-implement-story

Prerequisite: openlore analysis must exist (openlore analyze has been run). If orient returns "error": "no cache" → run analyze_codebase first, then retry.


Step 1 — Read the story and risk context

Read the story file. Extract:

  • $STORY_TITLE, $AC (acceptance criteria), $PROJECT_ROOT
  • $RISK_CONTEXT — the risk_context section if present (pre-filled by Architect Agent)
SituationApproach
risk_context present, risk 🟢 < 40Skip to Step 3 — use insertion point from context
risk_context present, risk 🟡 40–69Run Step 2 impact check, then proceed
risk_context present, risk 🔴 ≥ 70Stop — a blocking refactor story must be resolved first
risk_context absentRun the full Step 2 orientation

Step 2 — Orient and assess risk

Call the openlore MCP tool orient with:

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

For the top 2 functions returned, get minimal context first (callers, callees, body, test coverage in one call):

// get_minimal_context
{
  "directory": "$PROJECT_ROOT",
  "functionName": "$FUNCTION_NAME"
}

What to read from the result before proceeding:

  • function.riskLevel — "high" means fanIn ≥ 30 or fanOut ≥ 15; the tool expanded caller/callee lists to 24. All shown entries are in scope.
  • callers[*].callType — all "awaited" = async interface frozen; changing signature or return type breaks every caller. Mixed = looser coupling.
  • callees[*].isExternal: true — function touches HTTP/DB boundary; new code paths may fail silently in tests (mocked) but loudly in production.
  • testedBy[*].confidence — "called" = direct test (strong). "imported" = test imports module only; vi.mock() can nullify it. Only "imported" entries = treat as effectively untested.

If riskLevel is "high" or any callee is external, check the cluster:

// get_cluster
{
  "directory": "$PROJECT_ROOT",
  "functionName": "$FUNCTION_NAME"
}
  • clusterDensity < 0.05 → sparse, change is isolated, proceed
  • clusterDensity 0.05–0.15 → check internalCallGraph for transitively dependent functions
  • clusterDensity > 0.15 → dense cluster; coordinate the whole cluster or discuss scope with user

Then check risk:

// analyze_impact
{
  "directory": "$PROJECT_ROOT",
  "symbol": "$FUNCTION_NAME",
  "depth": 2
}

If any function has riskScore ≥ 70: stop. Do not implement. Run /openlore-execute-refactor on the blocking function first, or create a blocking refactor task and return to this story once the risk is resolved.


Step 2.5 — Stack inventory (conditional)

Based on the story title and orient results, call the relevant inventory tool(s) before reading any source file. Skip if the story clearly involves none of these areas.

Story involvesToolPurpose
Data models / ORM / database / tablesget_schema_inventorySee existing tables and fields — don't re-invent what already exists
HTTP routes / API / endpointsget_route_inventorySee existing routes before adding new ones
Config / env vars / secretsget_env_varsIdentify which vars are required vs have defaults
UI componentsget_ui_componentsSee existing component props and framework

Call whichever openlore MCP inventory tool applies, e.g. get_schema_inventory with {"directory": "$PROJECT_ROOT"}.

Use the results to ground the implementation in existing schemas/routes — the plan cannot contradict what already exists.


Step 3 — Check the spec

First, verify that OpenSpec specs exist:

ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | wc -l

If 0 specs found:

No OpenSpec specs exist yet. search_specs will return empty results and check_spec_drift (Step 7) will flag everything as uncovered.

Recommended: run /openlore-generate after this story to create a spec baseline. You only need to do this once.

Continuing with structural analysis only.

Skip the search_specs call and go to Step 4.

If specs exist:

Call the openlore MCP tool search_specs with:

{
  "directory": "$PROJECT_ROOT",
  "query": "$STORY_TITLE",
  "limit": 5
}

If relevant requirements are found, read the domain spec before writing any code. Note any constraints that apply.


Step 3.5 — Audit spec coverage of the target domain

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

From the result, check:

  • staleDomains — if the target domain appears here, its spec is outdated. Run the openlore-repair host skill before implementing. It uses deterministic prepare_spec_repair evidence and the current host agent; do not silently switch to the optional paid standalone openlore generate pipeline.
  • hubGaps — uncovered hub functions. If the feature touches one of these, add it to the adversarial check in Step 4b (high blast radius + no spec = risk).

If both are clean, continue to Step 4 without action.


Step 4 — Find the insertion point

Use insertion_points from risk_context if present. Otherwise:

Call the openlore MCP tool suggest_insertion_points with:

{
  "directory": "$PROJECT_ROOT",
  "description": "$STORY_TITLE",
  "limit": 5
}

Read the skeleton of the target file by calling the openlore MCP tool get_function_skeleton with:

{
  "directory": "$PROJECT_ROOT",
  "filePath": "$TARGET_FILE"
}

Confirm the approach with the user before writing code.

Step 4b — Adversarial challenge

Before writing any code, state explicitly what could break with this approach. If .claude/antipatterns.md exists, read it and include any applicable patterns.

"Risk check on $INSERTION_POINT:

  • $CALLER_A and $CALLER_B depend on this function — verify their assumptions hold after the change.
  • $EDGE_CASE is not covered by the current test suite — add it in Step 6.
  • [if antipatterns apply] AP-NNN ($PATTERN_NAME) — $RULE — applies here because $REASON."

This is not a gate — do not wait for user input. It is a mandatory self-check that must appear in the output before the first line of code is written.

Step 4c — Record significant design choices

Before editing, call record_decision when the chosen approach establishes a module boundary, interface contract, dependency, non-obvious insertion point, or other meaningful architectural trade-off. Include the directory, rationale, consequences, and affected files. Skip self-evident local edits.


Step 5 — Implement

Apply changes in this order:

  1. New types/interfaces (if needed)
  2. Core logic at the insertion point
  3. Updated call sites (if any)

Do not touch functions outside the scope identified in Step 2 / risk_context without re-running the gate.

Small model constraint: if the model is under 13B parameters, each edit must touch a contiguous block of at most 50 lines. Split larger changes.


Step 6 — Tests

Both levels required before proceeding to Step 7.

Mandatory — existing tests must not regress: Run the full test suite. If any pre-existing test breaks, fix the regression before continuing.

Recommended — at least one new test per AC: Write a test that directly exercises the behaviour described in the acceptance criterion.

SituationAction
All tests green, new tests writtenProceed to Step 7
Existing test brokenFix regression. Do not proceed.
New test reveals a misunderstanding of the ACReturn to Step 5, adjust implementation
Brownfield: no existing test coverageWrite the new test anyway. Note the coverage gap.

Step 7 — Verify drift

Only run once tests are green.

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

Drift typeResolution
uncovered on new filesNote it — propose openlore generate post-sprint
gap on existing domainRun the openlore-repair host skill
staleFix the reference
No driftDone

Absolute constraints

  • Do not write code before Step 4 confirmation
  • If riskScore ≥ 70 — stop, do not work around it, run /openlore-execute-refactor first
  • Do not run check_spec_drift before tests are green
  • Do not propose a spec update on untested code

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.