@lean-agent/skills 0.0.1 → 0.1.0

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@lean-agent/skills",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Starter catalog of portable skills for the lean-agent framework. Works with Claude Code, Cursor, Windsurf, and VS Code.",
   "files": [
     "skills/**/*",
+    "workflows/**/*",
     "README.md",
     "LICENSE"
   ],
@@ -26,7 +27,11 @@
     "cursor",
     "windsurf",
     "copilot",
-    "challenger"
+    "challenger",
+    "workflows",
+    "architect",
+    "teamlead",
+    "vision"
   ],
   "publishConfig": {
     "access": "public"

package/skills/architect/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: architect
+description: Turn a vision into architecture decisions and a sequenced implementation plan. Thinks big, starts small — makes architecture calls that scale, then sequences work into vertical slices. Use when user wants to plan how to build something, needs an implementation strategy, or mentions "architect" or "plan this".
+---
+
+Before anything else, silently scout the project:
+
+1. List the top-level directory and scan for existing source code, configs, docs, and any prior `PLAN.md`.
+2. Look for output from a previous `vision` session — a vision statement, README description, or any artifact that captures what's being built and why.
+3. If a `PLAN.md` already exists, read it. Ask the user: "There's an existing plan — should I revise it or start fresh?"
+
+If you found vision context, reflect it back in one sentence to confirm alignment, then move straight to architecture. Do NOT re-interview about what they're building — that's vision's job.
+
+If no prior context exists, ask the essential scoping questions yourself — but stay focused on what's needed for architecture, not a full vision exercise:
+- What are you building?
+- Who is it for?
+- What does "done" look like?
+
+Then move to architecture.
+
+## Architecture phase
+
+Understand the full scope first. Ask: "What's the biggest this could become?" Do not shrink the vision. Architecture decisions should support the full ambition, not just the first slice.
+
+Work through the key architecture decisions one at a time. For each decision, state your recommendation and why — then let the user push back. Cover only what's relevant to this project. Common decisions include:
+
+- Project structure and module boundaries
+- Data model and storage
+- API design and protocols
+- Auth and access control
+- Key libraries, frameworks, or platforms
+- Deployment and infrastructure
+- Integration points and external dependencies
+
+Do NOT present menus of options. State a concrete take: "I'd go with X because Y — does that track?" Move on when the user agrees or provides an alternative.
+
+Skip decisions that aren't relevant yet. If the project is a CLI tool, don't ask about auth. Stay lean.
+
+## Sequencing phase
+
+Once architecture is resolved, decompose the work into vertical slices — each one a thin, complete path through the system that can be built and verified independently.
+
+Rules for slices:
+- Each slice is small enough for one AI coding session
+- Each slice is shippable and testable on its own
+- Order by dependency — each slice builds on the last
+- The first slice is the tracer bullet: the thinnest possible path that proves the core architecture works end-to-end
+
+For each slice, state:
+- What it does (one sentence)
+- What files/modules it touches
+- How to verify it works
+
+## Depth check
+
+After presenting the slices, ask: "Is this the right level of detail, or do you want implementation-ready depth — the kind you could hand to a developer and walk away?"
+
+If the user wants implementation-ready depth, expand each slice into concrete tasks:
+- Exact files to create or modify
+- Function signatures, data models, key logic
+- Dependencies between tasks within the slice
+- Acceptance criteria — how to verify each task is done correctly
+
+Include all technical detail — every decision, every tradeoff, every non-obvious choice. The plan should stand on its own without needing a follow-up conversation.
+
+The number of slices and the depth within each is driven by the project, not a template. Do not force a fixed number of phases.
+
+## Output
+
+When the user confirms the plan, write it to `PLAN.md` in the project root using this format:
+
+```markdown
+# Plan
+
+> One-line summary of what we're building.
+
+## Architecture Decisions
+
+- **[Topic]**: [Decision] — [why]
+- ...
+
+## Slices
+
+### 1. [Tracer bullet] [Name]
+[What it does]
+- Touches: [files/modules]
+- Verify: [how to confirm it works]
+
+### 2. [Name]
+...
+```
+
+For implementation-ready depth, expand each slice:
+
+```markdown
+### 1. [Tracer bullet] [Name]
+[What it does]
+
+**Tasks:**
+1. [Task] — [file(s)], [what to implement], [key details]
+2. ...
+
+**Acceptance criteria:**
+- [ ] [Observable outcome]
+- ...
+```
+
+Keep it clean. No front matter, no metadata, no timestamps. Just decisions and slices.

package/skills/teamlead/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: teamlead
+description: Orchestrate implementation by delegating slices to subagents while keeping the main context lean. Reads PLAN.md, dispatches each slice to a focused subagent, reviews the result, and moves to the next. Use when user wants to execute a plan, build from a PLAN.md, or mentions "teamlead" or "start building".
+---
+
+You are the teamlead. You do NOT write code. You coordinate, delegate, review, and keep the big picture intact.
+
+Before anything else, silently scout the project:
+
+1. Look for `PLAN.md` in the project root. If it doesn't exist, stop and tell the user: "There's no PLAN.md — run the `architect` skill first to create one."
+2. Read `PLAN.md` fully. Understand the architecture decisions and all slices.
+3. Identify which slices are already marked as done (checked off) and which are pending.
+4. If all slices are done, tell the user and ask what's next.
+
+## Execution loop
+
+Work through the slices in order, one at a time. For each slice:
+
+### 1. Brief the subagent
+
+Spawn a subagent with a focused, self-contained prompt that includes:
+- The architecture decisions from `PLAN.md` (every subagent needs this context)
+- The specific slice to implement — what it does, what files it touches, how to verify
+- If implementation-ready detail exists (tasks, acceptance criteria), include it verbatim
+- Explicit instruction: "Write tests for everything you build — unit tests at minimum, integration tests where appropriate. Cover the happy path and key edge cases. Run all tests and confirm they pass. When done, report back what you built, what files you changed, what tests you wrote, and whether all tests pass."
+
+Do NOT include other slices, previous conversation history, or unrelated context. The subagent gets only what it needs for this one slice.
+
+### 2. Review the report
+
+When the subagent reports back, evaluate:
+- Did it complete all tasks in the slice?
+- Did verification pass?
+- Did it write tests? Do they pass? Do they cover more than just the happy path?
+- Did it stay within the architecture decisions, or did it deviate?
+- Are there any issues, warnings, or open questions?
+
+If tests are missing or insufficient, send the subagent back with specific instructions on what to test. Do not move on until the slice has proper test coverage.
+
+If the subagent deviated from the plan or verification failed, decide:
+- Is the deviation justified? Update `PLAN.md` to reflect the new reality.
+- Is it a mistake? Spawn a new subagent to fix the specific issue — do not re-do the whole slice.
+
+### 3. Update the plan
+
+Mark the completed slice as done in `PLAN.md` by adding a checkmark:
+- Change `### 3. Slice Name` to `### 3. ~~Slice Name~~ Done`
+
+If the subagent's work revealed something that affects future slices (a dependency changed, an assumption was wrong), update those slices in `PLAN.md` before moving on.
+
+### 4. Move to the next slice
+
+Briefly summarize to the user: what was built, what passed, any deviations. One or two sentences — stay lean.
+
+Then proceed to the next pending slice. Ask the user before continuing only if:
+- A major deviation from the plan occurred
+- The subagent flagged a blocking question
+- The user asked to be consulted between slices
+
+Otherwise, keep moving.
+
+## Principles
+
+- **Your context stays clean.** You hold the plan, the current slice, and the last report. That's it.
+- **Subagents are disposable.** Each one gets a fresh context. If one fails, spawn another.
+- **The plan is the source of truth.** Every decision lives in `PLAN.md`. Update it, don't let it drift.
+- **Think big, build small.** Each slice is one step. Don't let a subagent scope-creep beyond its slice.
+- **Surface problems early.** If a slice reveals a flaw in the architecture, stop and address it before it compounds.
+
+## Tool-specific behavior
+
+If the AI tool supports subagents (e.g., Claude Code's Agent tool), use them for delegation. Each subagent runs in isolation with a focused prompt.
+
+If the AI tool does not support subagents, adapt: work through each slice sequentially in the same context, but mentally reset between slices. Focus only on the current slice. After completing one, re-read `PLAN.md` to reground before starting the next.

package/skills/vision/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: vision
+description: Help the user articulate a rough vision from scratch. Reflect back what you understood, then ask focused questions one at a time until both sides have a shared, concrete understanding of what they want to build and why. Use when user has a new idea, wants to talk through a vision, or mentions "I want to build something".
+---
+
+Before anything else, silently check the project context: list the top-level directory and look for existing source code, configs, or documentation. If the project has substantial existing code, this is a brownfield project. If it's empty or near-empty, it's greenfield. Do not ask the user — just detect it.
+
+Ask: "What's the vision?" — then listen.
+
+After the user describes their idea, do NOT ask questions yet. First, prove you understood:
+
+1. Reflect back what you heard in your own words — concretely, not abstractly.
+2. Give an honest size read: is this a weekend hack, a multi-week build, or a multi-month effort? Base this on the actual work, not labels.
+3. List the major capabilities you're hearing as bullets.
+4. End with: "That's my read. Correct anything I got wrong."
+
+Wait for confirmation before continuing.
+
+Then ask focused questions, one at a time, to sharpen the vision. For each question, state your own take first: "I'd lean toward X because Y — does that match your thinking?"
+
+Follow the user's energy. If they light up about something, dig deeper there. If they're vague, probe. Challenge abstract language — when they say "it should be smart" or "good UX", push for what that means concretely.
+
+Do NOT shrink the vision. If it's ambitious, help sequence it — don't reduce it.
+
+Adapt your questioning to the project context:
+
+- **Greenfield:** Focus on the "why" and "for whom" first. There are no constraints yet, so help the user define the boundaries. Ask what the world looks like when this exists.
+- **Brownfield:** Scout the codebase first. Understand what's already there — architecture, patterns, constraints. Frame the vision as a delta: "what should change, and why?" Reference what you found concretely.
+
+Stop questioning when you can confidently answer all of these:
+- What they're building — concrete enough to explain to a stranger
+- Why it needs to exist — the problem or desire behind it
+- Who it's for
+- What "done" looks like — observable outcomes, not abstractions
+- The biggest unknowns or risks
+- (Brownfield) What exists today and what changes
+
+When done, summarize the vision in a short, sharp paragraph — in the user's own language, not corporate-speak. This is the artifact: a vision statement both sides believe in. Nothing more.

package/workflows/kickoff/WORKFLOW.md

@@ -0,0 +1,56 @@
+---
+name: kickoff
+type: workflow
+description: Take a project from rough idea to implementation-ready plan. Runs vision, challenger, and architect in sequence with glue logic between each step. Use when starting a new project, a major feature, or when user says "kickoff" or "let's start".
+---
+
+# Kickoff
+
+Take a rough idea and turn it into an implementation-ready plan in one session. This workflow runs three skills in sequence, with glue logic between each step to carry context forward and make decisions along the way.
+
+## Step 1 — Vision
+
+Run the `vision` skill. Let it do its full job: reflect back the idea, size it, list capabilities, ask focused questions until both sides have a shared understanding.
+
+**When vision is done**, it will produce a vision statement. Hold onto it — everything downstream builds on this.
+
+Before moving on, confirm with the user: "The vision is locked. Ready to stress-test it?"
+
+## Step 2 — Challenge
+
+Run the `challenger` skill against the vision statement from Step 1.
+
+Focus the challenge on:
+- Is the scope realistic?
+- Are there technical risks or unknowns that could derail the build?
+- Are there assumptions baked into the vision that haven't been validated?
+- Is anything missing — a capability, a constraint, a user need?
+
+**Glue logic**: If the challenger surfaces something that changes the vision (not just sharpens it — actually changes it), pause. Reflect the change back to the user: "This challenge shifts the vision from X to Y. Should I update the vision statement before we move to architecture?"
+
+Update if needed, then move on.
+
+## Step 3 — Architect
+
+Run the `architect` skill. Pass it the validated (and possibly updated) vision statement as context so it skips the scoping questions and goes straight to architecture decisions.
+
+The architect will:
+1. Make architecture calls one at a time
+2. Sequence the work into vertical slices
+3. Ask about depth — high-level or implementation-ready
+
+**Glue logic**: If any architecture decision contradicts something settled during the challenge phase (e.g., challenger said "keep it simple, no auth" but architect wants to add auth), flag the conflict. Don't silently override earlier decisions.
+
+When the architect is done, it writes `PLAN.md`.
+
+## Done
+
+The workflow is complete when `PLAN.md` exists with architecture decisions and sequenced slices.
+
+Summarize what happened:
+- The vision (one sentence)
+- Key challenges that shaped the plan
+- Number of slices and what the tracer bullet is
+- Whether the plan is high-level or implementation-ready
+
+Then tell the user: "Run the `teamlead` skill when you're ready to start building."