@atheneworkai/speci5 0.1.0 → 0.1.2

package/README.md

@@ -7,7 +7,7 @@ A spec-driven development framework for AI-assisted coding. Gives your AI coding
 Add speci5 to any project:
 
 ```bash
-npx speci5 init
+npx @atheneworkai/speci5 init
 ```
 
 This copies the skill definitions and config into your repo:
@@ -22,7 +22,7 @@ CLAUDE.md                          # Framework instructions for your AI agent
 To update to the latest version:
 
 ```bash
-npx speci5 update
+npx @atheneworkai/speci5 update
 ```
 
 ## Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atheneworkai/speci5",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Spec-driven development framework for AI-assisted coding",
   "type": "module",
   "bin": {

package/skills/speci5.plan/SKILL.md

@@ -6,7 +6,13 @@ argument-hint: "Path to the story folder, e.g. .spec/features/user-auth/login-wi
 
 # Plan
 
-Read a story spec and create a concrete implementation plan with tasks.
+Read a story spec and create a concrete implementation plan.
+
+Start by understanding the story and the codebase, then produce specific, actionable tasks. Only ask questions if the spec has genuine ambiguities that would lead to a wrong plan.
+
+<HARD-GATE>
+Do NOT implement code, modify specs, create features, or brainstorm ideas. This skill ONLY produces plan files in `.spec/features/<feature>/<story>/plan.md`.
+</HARD-GATE>
 
 ## Triggers
 
@@ -23,17 +29,29 @@ Activate this skill when the user wants to:
 3. If a `plan.md` already exists, update it — preserve any checked-off tasks and add/revise remaining ones.
 4. Do NOT modify `story.md` or `feature.md` — those are the **specify** skill's domain.
 5. Do NOT implement the code — only produce the plan.
+6. **YAGNI ruthlessly** — Every task must tie back to an acceptance criterion. If it doesn't serve the story, leave it out.
+
+## Conversation Style
+
+- **Bias toward action.** If the story and codebase give enough information, produce the plan directly.
+- **Only ask when genuinely blocked** — ambiguous acceptance criteria, multiple conflicting interpretations, or a technical decision with no clear answer.
+- **One question at a time** if you do need to ask.
+- **Prefer multiple choice** when possible.
 
 ## Steps
 
 1. **Read the story** — Load `.spec/features/<feature>/<story>/story.md`.
 2. **Read the feature** — Load the parent `feature.md` for broader context.
-3. **Analyze the codebase** — Understand:
+3. **Analyze the codebase** — Go beyond the story. Understand:
    - Project structure, tech stack, and conventions.
    - What related code already exists.
    - Where new code should be placed.
-4. **Break down tasks** — Convert acceptance criteria into ordered, actionable implementation tasks with specific file paths and module names.
-5. **Write the plan** — Save to `.spec/features/<feature>/<story>/plan.md`.
+   - Existing patterns to follow (routing conventions, test structure, naming, etc.).
+4. **Check scope** — If the story is too large or covers multiple independent concerns, flag it. Help decompose into smaller stories before planning. Each plan should be completable in a focused session.
+5. **Ask clarifying questions (only if needed)** — If acceptance criteria are genuinely ambiguous or a technical decision has no clear answer from the codebase, ask. Otherwise, proceed.
+6. **Propose 2-3 implementation approaches** — Present different strategies with trade-offs (e.g., new module vs. extending existing, library vs. hand-rolled). Lead with your recommendation and explain why.
+7. **Write the plan** — Once aligned with the user, write ordered, actionable tasks to `.spec/features/<feature>/<story>/plan.md`.
+8. **Present for review** — Show the plan and confirm it looks right before considering the job done.
 
 ## Output Format
 

package/skills/speci5.plan/assets/output.md

@@ -6,6 +6,10 @@ Write to `.spec/features/<feature>/<story>/plan.md`:
 ## Context
 Brief summary of what this plan implements and any technical decisions.
 
+## Approach
+Which implementation approach was chosen and why.
+Note any alternatives considered and why they were ruled out.
+
 ## Tasks
 - [ ] Task 1 — description with specifics (file paths, function names, etc.)
 - [ ] Task 2 — description

package/skills/speci5.specify/SKILL.md

@@ -8,6 +8,12 @@ argument-hint: "Name the idea(s) to specify, or leave blank to process all ideas
 
 Transform idea documents into structured feature and story specs.
 
+Start by understanding the ideas and the existing codebase, then produce clear, testable specifications. Only ask questions if the idea has genuine ambiguities that would lead to a wrong spec.
+
+<HARD-GATE>
+Do NOT create plan files, implement code, or brainstorm ideas. This skill ONLY produces `feature.md` and `story.md` files in `.spec/features/`. The **plan** skill is the next step.
+</HARD-GATE>
+
 ## Triggers
 
 Activate this skill when the user wants to:
@@ -25,14 +31,26 @@ Activate this skill when the user wants to:
 5. Link stories in `feature.md` using relative paths.
 6. If features/stories already exist, update them — do not overwrite human edits.
 7. Present the proposed feature/story breakdown to the user for confirmation before writing files.
+8. **YAGNI ruthlessly** — If a story isn't clearly needed for the feature's goals, leave it out. Fewer well-defined stories beat many vague ones.
+
+## Conversation Style
+
+- **Bias toward action.** If the idea and codebase give enough information, produce the specs directly.
+- **Only ask when genuinely blocked** — ambiguous intent, multiple conflicting interpretations, or missing information that can't be inferred.
+- **One question at a time** if you do need to ask.
+- **Prefer multiple choice** when possible.
 
 ## Steps
 
 1. **Read ideas** — Read the specified idea file(s) from `.spec/ideas/`. If none specified, read all.
-2. **Read existing specs** — Scan `.spec/features/` to avoid duplicating or conflicting with what's already specified.
-3. **Synthesize** — Break ideas into **features** (cohesive capabilities) and **stories** (independently deliverable slices of a feature).
-4. **Propose** — Present the feature/story breakdown to the user for confirmation.
-5. **Write specs** — For each feature, create a folder with `feature.md`. For each story, create a subfolder with `story.md`.
+2. **Explore project context** — Go beyond the ideas. Check the codebase, docs, and existing specs to understand what's already built, what conventions exist, and what patterns to follow. Specs should be grounded in reality.
+3. **Read existing specs** — Scan `.spec/features/` to avoid duplicating or conflicting with what's already specified.
+4. **Check scope** — If an idea covers multiple independent capabilities or is too broad, flag it. Help decompose into separate features before specifying. Each feature should be a single cohesive capability.
+5. **Ask clarifying questions (only if needed)** — If the idea has genuine ambiguities or missing information that can't be inferred from context, ask. Otherwise, proceed.
+6. **Synthesize** — Break ideas into **features** (cohesive capabilities) and **stories** (independently deliverable slices of a feature).
+7. **Propose** — Present the feature/story breakdown with a brief rationale. Get user confirmation before writing files.
+8. **Write specs** — For each feature, create a folder with `feature.md`. For each story, create a subfolder with `story.md`.
+9. **Present for review** — Show the written specs and confirm they look right before considering the job done.
 
 ## Folder Structure
 

package/skills/speci5.specify/assets/output.md

@@ -12,6 +12,9 @@ What this feature is and why it matters.
 - Goal 1
 - Goal 2
 
+## Non-Goals
+- What this feature explicitly does NOT cover.
+
 ## Stories
 - [<story-title>](<story-slug>/)
 - [<story-title>](<story-slug>/)
@@ -31,4 +34,7 @@ As a <role>, I can <action> so that <benefit>.
 - [ ] Criterion 1
 - [ ] Criterion 2
 - [ ] Criterion 3
+
+## Open Questions
+- Any unresolved questions that may affect implementation.
 ```