@atheneworkai/speci5 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# speci5
+
+A spec-driven development framework for AI-assisted coding. Gives your AI coding agent a structured workflow: **brainstorm** → **specify** → **plan** → **check**.
+
+## Install
+
+Add speci5 to any project:
+
+```bash
+npx speci5 init
+```
+
+This copies the skill definitions and config into your repo:
+
+```
+CLAUDE.md                          # Framework instructions for your AI agent
+.claude/skills/                    # Skill definitions (slash commands)
+.spec/ideas/                       # Your brainstormed ideas go here
+.spec/features/                    # Structured specs land here
+```
+
+To update to the latest version:
+
+```bash
+npx speci5 update
+```
+
+## Usage
+
+Once installed, the skills are available as `/slash` commands in Copilot Chat:
+
+| Command | What it does |
+|---------|-------------|
+| `/speci5.brainstorm` | Elaborate rough thoughts into structured idea documents |
+| `/speci5.specify` | Transform ideas into feature and story specs |
+| `/speci5.plan` | Create concrete implementation tasks from a story |
+| `/speci5.check` | Verify code against a story's plan and update progress |
+
+### Workflow
+
+```
+1. /speci5.brainstorm "user authentication with OAuth"
+   → writes .spec/ideas/user-auth-oauth.md
+
+2. /speci5.specify
+   → writes .spec/features/user-auth/feature.md
+   → writes .spec/features/user-auth/oauth-login/story.md
+
+3. /speci5.plan .spec/features/user-auth/oauth-login
+   → writes .spec/features/user-auth/oauth-login/plan.md
+
+4. (implement the code)
+
+5. /speci5.check .spec/features/user-auth/oauth-login
+   → updates plan.md checkboxes, reports progress
+```
+
+## How it works
+
+Speci5 is a set of AI coding skills that enforce a spec-driven workflow. Instead of jumping straight to code, you capture ideas, break them into features and stories with acceptance criteria, then create concrete implementation plans — all tracked in `.spec/` alongside your code.
+
+See [CLAUDE.md](CLAUDE.md) for the full framework reference.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { homedir as osHomedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const CWD = process.cwd();
+const HOME = osHomedir();
+
+const SKILLS = [
+  'speci5.brainstorm',
+  'speci5.check',
+  'speci5.plan',
+  'speci5.specify',
+];
+
+const command = process.argv[2];
+const force = process.argv.includes('--force');
+const userLevel = process.argv.includes('--user');
+
+async function main() {
+  switch (command) {
+    case 'init':
+      await init();
+      break;
+    case 'update':
+      await update();
+      break;
+    default:
+      printUsage();
+      break;
+  }
+}
+
+function printUsage() {
+  const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+  console.log(`
+speci5 v${pkg.version} — Spec-Driven Development Framework
+
+Usage: npx speci5 <command>
+
+Commands:
+  init     Install speci5 skills and config into the current project
+  update   Update existing speci5 installation to latest version
+
+Options:
+  --user   Install skills at user level (~/.claude/skills) instead of project level
+  --force  Overwrite existing files without prompting
+`);
+}
+
+async function init() {
+  const scope = userLevel ? 'user' : 'project';
+  const destBase = userLevel ? HOME : CWD;
+  const label = userLevel ? '~/.claude/skills' : '.claude/skills';
+
+  console.log(`\nspeci5 — Installing skills at ${scope} level (${label})\n`);
+
+  const skillsDir = join(destBase, '.claude', 'skills');
+  const existing = SKILLS.filter(s => existsSync(join(skillsDir, s)));
+
+  if (existing.length > 0 && !force) {
+    console.log('Found existing skills:');
+    existing.forEach(s => console.log(`  ${label}/${s}/`));
+
+    const answer = await confirm('\nOverwrite? (y/N) ');
+    if (!answer) {
+      console.log('Aborted.\n');
+      process.exit(0);
+    }
+  }
+
+  copyFiles(destBase, label);
+
+  if (!userLevel) {
+    createSpecDir();
+  }
+
+  const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+  writeConfig({ version: pkg.version, scope });
+
+  console.log(`
+Done! speci5 installed at ${scope} level.
+
+Next steps:
+  1. Skills are available as /slash commands in Copilot Chat
+  2. Start with: /speci5.brainstorm to capture an idea
+  3. Then: /speci5.specify -> /speci5.plan -> /speci5.check
+`);
+}
+
+async function update() {
+  const config = readConfig();
+  const scope = userLevel ? 'user' : (config.scope || 'project');
+  const destBase = scope === 'user' ? HOME : CWD;
+  const label = scope === 'user' ? '~/.claude/skills' : '.claude/skills';
+
+  console.log(`\nspeci5 — Updating ${scope}-level skills\n`);
+  copyFiles(destBase, label);
+
+  const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+  writeConfig({ version: pkg.version, scope });
+
+  console.log('\nDone! speci5 updated successfully.\n');
+}
+
+function readConfig() {
+  const configPath = join(CWD, '.speci5.config.yml');
+  if (!existsSync(configPath)) return {};
+  const content = readFileSync(configPath, 'utf8');
+  const config = {};
+  for (const line of content.split('\n')) {
+    const match = line.match(/^(\w+):\s*"?([^"]+)"?\s*$/);
+    if (match) config[match[1]] = match[2];
+  }
+  return config;
+}
+
+function copyFiles(destBase, label) {
+  for (const skill of SKILLS) {
+    const skillSrc = join(PKG_ROOT, 'skills', skill);
+    const skillDest = join(destBase, '.claude', 'skills', skill);
+    mkdirSync(skillDest, { recursive: true });
+    cpSync(skillSrc, skillDest, { recursive: true });
+    console.log(`  ${label}/${skill}/`);
+  }
+}
+
+function createSpecDir() {
+  const specDir = join(CWD, '.spec', 'ideas');
+  if (!existsSync(specDir)) {
+    mkdirSync(specDir, { recursive: true });
+    console.log('  .spec/ideas/');
+  }
+  const featuresDir = join(CWD, '.spec', 'features');
+  if (!existsSync(featuresDir)) {
+    mkdirSync(featuresDir, { recursive: true });
+    console.log('  .spec/features/');
+  }
+}
+
+function writeConfig({ version, scope }) {
+  const configPath = join(CWD, '.speci5.config.yml');
+  const lines = [
+    `# speci5 configuration`,
+    `# Generated by speci5 init — edit freely`,
+    ``,
+    `version: "${version}"`,
+    `scope: ${scope}`,
+  ];
+  writeFileSync(configPath, lines.join('\n') + '\n');
+  console.log('  .speci5.config.yml');
+}
+
+function confirm(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(prompt, answer => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+main().catch(err => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@atheneworkai/speci5",
+  "version": "0.1.0",
+  "description": "Spec-driven development framework for AI-assisted coding",
+  "type": "module",
+  "bin": {
+    "speci5": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
+  "keywords": [
+    "spec",
+    "ai",
+    "copilot",
+    "claude",
+    "development",
+    "workflow",
+    "skills",
+    "spec driven development"
+  ],
+  "author": "David Nguyen",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/speci5.brainstorm/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: speci5.brainstorm
+description: "Elaborate and expand user input into structured idea documents in .spec/ideas/. Takes rough thoughts, researches patterns, surfaces trade-offs and open questions. WHEN: /brainstorm, brainstorm idea, new idea, capture idea, explore concept, elaborate on, think about, research idea. DO NOT USE FOR: writing specs (use specify), creating plans (use plan), checking implementation (use check)."
+argument-hint: "Describe the idea or concept you want to brainstorm"
+---
+
+# Brainstorm
+
+Turn rough ideas into well-structured idea documents through collaborative dialogue.
+
+Start by understanding the project context and the user's intent, then ask clarifying questions before elaborating. The goal is a thinking artifact — not a formal spec.
+
+<HARD-GATE>
+Do NOT create feature files, story files, specs, plans, or code. This skill ONLY produces idea documents in `.spec/ideas/`. The **specify** skill is the next step.
+</HARD-GATE>
+
+## Triggers
+
+Activate this skill when the user wants to:
+- Capture a new idea or concept
+- Elaborate on a rough thought
+- Research patterns, prior art, or trade-offs for an idea
+- Update or refine an existing idea document
+
+## Rules
+
+1. Use **kebab-case** for all filenames (e.g., `user-auth.md`).
+2. Do NOT create feature or story files — that's the **specify** skill's job.
+3. If updating an existing idea, preserve human-written content and append/refine rather than overwrite.
+4. Keep language clear and concise — this is a thinking artifact, not a formal spec.
+5. **YAGNI ruthlessly** — Strip unnecessary complexity. Simpler ideas are better ideas. If a feature isn't clearly needed, leave it out.
+
+## Conversation Style
+
+- **One question at a time.** Don't overwhelm the user with multiple questions in one message.
+- **Prefer multiple choice** when possible — easier to answer than open-ended.
+- **Be flexible** — go back and clarify when something doesn't make sense.
+
+## Steps
+
+1. **Explore project context** — Scan `.spec/ideas/` for existing ideas, but also check the codebase, docs, and recent changes to understand what's already built and what patterns are in use. Ideas don't exist in a vacuum.
+2. **Check scope** — If the user's input describes multiple independent subsystems or a very large surface area, flag this immediately. Help decompose into smaller, independent ideas before elaborating. Each idea should be a single cohesive concept.
+3. **Ask clarifying questions** — Before writing anything, ask questions one at a time to understand purpose, constraints, and success criteria. Don't skip this even for "simple" ideas — unexamined assumptions cause the most wasted work.
+4. **Propose 2-3 approaches** — Present different ways to tackle the idea, with trade-offs for each. Lead with your recommendation and explain why.
+5. **Write or update** — Once you and the user are aligned, write the idea document. If the input closely relates to an existing idea file, **update** it. Otherwise, **create** a new file in `.spec/ideas/`.
+6. **Present** — Show the user the resulting idea document and highlight any open questions.
+
+## Output Format
+
+See [output template](./assets/output.md).

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

@@ -0,0 +1,28 @@
+Write to `.spec/ideas/<slug>.md` using this structure:
+
+```markdown
+# <Idea Title>
+
+## Context
+Why this idea matters. Background and motivation.
+
+## Description
+Detailed elaboration of the idea.
+
+## Approaches Considered
+### Approach A: <Name> (Recommended)
+Brief description. Why this is the recommended path.
+- **Pros:** ...
+- **Cons:** ...
+
+### Approach B: <Name>
+Brief description.
+- **Pros:** ...
+- **Cons:** ...
+
+## Key Considerations
+- Bullet points covering edge cases, trade-offs, constraints.
+
+## Open Questions
+- Unresolved questions that need human input before specifying.
+```

package/skills/speci5.check/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: speci5.check
+description: "Verify implementation progress by inspecting source code against a story's plan. Reads plan.md tasks, searches the codebase for evidence of completion, and toggles task checkboxes. WHEN: /check, check progress, verify implementation, check story, are tasks done, update plan status, check plan. DO NOT USE FOR: brainstorming ideas (use brainstorm), writing specs (use specify), creating plans (use plan)."
+argument-hint: "Path to the story folder, e.g. .spec/features/user-auth/login-with-email"
+---
+
+# Check
+
+Verify implementation progress by inspecting source code against a story's plan.
+
+## Triggers
+
+Activate this skill when the user wants to:
+- Verify if planned tasks have been implemented
+- Check progress on a story
+- Update task checkboxes based on current code state
+- Get a status report on implementation progress
+
+## Rules
+
+1. Do NOT modify source code — this is a **read-only verification** skill.
+2. Do NOT modify `story.md` or `feature.md`.
+3. Only modify `plan.md` to toggle task checkboxes and add brief inline notes.
+4. Be **conservative** — only mark a task complete if there is clear evidence in the code.
+5. If a task is partially done, leave it unchecked and note what's missing.
+
+## Steps
+
+1. **Read the plan** — Load `.spec/features/<feature>/<story>/plan.md`.
+2. **Read the story** — Load `story.md` to understand acceptance criteria context.
+3. **Verify each task** — For each task in the plan:
+   - Search the codebase for the specific files, functions, routes, components, or tests mentioned.
+   - Evaluate whether the implementation satisfies the task's intent, not just that a file exists.
+4. **Update plan.md** — Toggle checkboxes:
+   - Completed: `- [ ]` → `- [x]`
+   - Regressed (removed/broken): `- [x]` → `- [ ]`
+   - Uncertain: leave unchecked, add a note.
+5. **Report summary** — Present results to the user.
+
+## Output
+
+See [output template](./assets/output.md).

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

@@ -0,0 +1,13 @@
+After updating `plan.md`, print a summary:
+
+```
+## Check Summary: <Story Title>
+
+Progress: X/Y tasks complete
+
+### Completed
+- ✅ Task description
+
+### Remaining
+- ⬜ Task description — (reason or what's missing)
+```

package/skills/speci5.plan/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: speci5.plan
+description: "Read a story spec and create a concrete implementation plan with tasks in .spec/features/<feature>/<story>/plan.md. Analyzes the codebase to produce specific, actionable tasks with file paths and function names. WHEN: /plan, create plan, plan story, break down story, implementation tasks, plan implementation, what to build. DO NOT USE FOR: brainstorming ideas (use brainstorm), writing specs (use specify), checking implementation (use check)."
+argument-hint: "Path to the story folder, e.g. .spec/features/user-auth/login-with-email"
+---
+
+# Plan
+
+Read a story spec and create a concrete implementation plan with tasks.
+
+## Triggers
+
+Activate this skill when the user wants to:
+- Create an implementation plan for a story
+- Break a story into concrete development tasks
+- Understand what needs to be built for a story
+- Update an existing plan with revised tasks
+
+## Rules
+
+1. Tasks must be **specific and actionable** — not vague ("implement feature") but concrete ("Create `POST /api/auth/login` route in `src/routes/auth.ts`").
+2. Include tasks for tests where the story's acceptance criteria warrant them.
+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.
+
+## 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:
+   - 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`.
+
+## Output Format
+
+See [output template](./assets/output.md).

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

@@ -0,0 +1,13 @@
+Write to `.spec/features/<feature>/<story>/plan.md`:
+
+```markdown
+# Plan: <Story Title>
+
+## Context
+Brief summary of what this plan implements and any technical decisions.
+
+## Tasks
+- [ ] Task 1 — description with specifics (file paths, function names, etc.)
+- [ ] Task 2 — description
+- [ ] Task 3 — description
+```

package/skills/speci5.specify/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: speci5.specify
+description: "Transform idea documents from .spec/ideas/ into structured feature and story specs in .spec/features/. Creates feature.md and story.md files organized by feature folders and story subfolders. WHEN: /specify, write spec, create spec, turn idea into spec, specify feature, define stories, break down feature, structure requirements. DO NOT USE FOR: brainstorming ideas (use brainstorm), creating plans (use plan), checking implementation (use check)."
+argument-hint: "Name the idea(s) to specify, or leave blank to process all ideas"
+---
+
+# Specify
+
+Transform idea documents into structured feature and story specs.
+
+## Triggers
+
+Activate this skill when the user wants to:
+- Convert ideas into formal feature/story specifications
+- Break a feature down into deliverable stories
+- Create or update feature and story specs
+- Structure requirements from idea documents
+
+## Rules
+
+1. Use **kebab-case** for all folder and file names.
+2. Each story must have concrete, testable acceptance criteria.
+3. Stories should be small enough to implement in a single focused effort.
+4. Do NOT create `plan.md` files — that's the **plan** skill's job.
+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.
+
+## 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`.
+
+## Folder Structure
+
+```
+.spec/features/
+  <feature-slug>/
+    feature.md
+    <story-slug>/
+      story.md
+```
+
+## Output Formats
+
+See [output templates](./assets/output.md).

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

@@ -0,0 +1,34 @@
+## feature.md
+
+Write to `.spec/features/<feature-slug>/feature.md`:
+
+```markdown
+# Feature: <Feature Title>
+
+## Overview
+What this feature is and why it matters.
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Stories
+- [<story-title>](<story-slug>/)
+- [<story-title>](<story-slug>/)
+```
+
+## story.md
+
+Write to `.spec/features/<feature-slug>/<story-slug>/story.md`:
+
+```markdown
+# Story: <Story Title>
+
+## Description
+As a <role>, I can <action> so that <benefit>.
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+```