@radenadri/skills-alena 1.2.0 → 1.2.1

package/README.md

@@ -24,31 +24,23 @@
 
 **ALENA** is a personal toolkit for autonomous, networked AI agents. The long form is **Autonomous Layer for Executing Networked Agents**. Install once, use everywhere — across **34+ supported agents** including Antigravity, Cursor, Claude Code, Gemini CLI, Windsurf, Copilot, and more.
 
-### 📄 PRD Creation Flow
-
-ALENA now ships a local PRD creation path for teams that want product clarification before implementation. The flow is built around:
-
-- a wrapper skill at `skills/write-prd/`
-- a Claude Code command at `commands/prd.md`
-- an Antigravity workflow at `workflows/prd.md`
-
-`write-prd` is not the same as `writing-plans`. `write-prd` is interview-first and product-first: it clarifies the user, problem, goals, non-goals, and success definition before drafting a reusable product requirements document. `writing-plans` starts after that, when the approved PRD needs to turn into implementation work.
-
 ---
 
-### 💎 The Gem: LLM Council v2 + Memory Module
+## 💎 LLM Council v2 — Agent Team Coordination
 
-> The most powerful pattern in AI-assisted development — real subagent spawning with deterministic orchestration.
+### The Problem
+AI coding tasks fail at scale because no single agent can hold all context: database schemas, API routes, service dependencies, frontend components, and business logic — simultaneously. Linear handoffs lose context. Role-switching in a single context window wastes tokens.
 
-**The Memory Module** deeply scans your entire codebase BEFORE any work begins — databases, schemas, API routes, service dependencies, frontend components, tech stack — and creates a structured intelligence layer that persists across sessions.
+### The Solution: Real Subagent Spawning + Deterministic Orchestration
 
-**Council v2** spawns **real subagents** via `Task()` — each specialist gets a fresh 200k context window. The orchestrator stays lean at ~10-15% context, coordinating through 13 deterministic CLI commands with code-enforced quality gates.
+**Council v2** replaces the old role-switching pattern with **real subagent spawning** via `Task()`. Each specialist agent gets a fresh 200k context window — no shared context pollution. The orchestrator stays lean at ~10-15% context usage.
 
 ```
                     ╔═══════════════════════════════╗
-                    ║     🎯 ORCHESTRATOR (lean)     ║
-                    ║  13 CLI commands · Quality gates ║
-                    ║  ~10-15% context · Task() spawn  ║
+                    ║     🎯 ORCHESTRATOR (lean)      ║
+                    ║  ~10-15% context usage           ║
+                    ║  13 deterministic CLI commands    ║
+                    ║  Code-enforced quality gates      ║
                     ╚════════════╦══════════════════╝
                                  ║
                         Task() spawning
@@ -60,6 +52,17 @@ ALENA now ships a local PRD creation path for teams that want product clarificat
        └──────────┘ └────────┘ └──────┘ └─────────┘
 ```
 
+### Key Capabilities
+
+| Capability | Description |
+|:---|:---|
+| 🧠 **Real subagent spawning** | Each agent gets a fresh 200k context via `Task()` — no shared context pollution |
+| 🎛️ **13 CLI commands** | Deterministic state machine for council orchestration (`council start`, `council next`, `council status`, etc.) |
+| 🚪 **Code-enforced quality gates** | Agents cannot advance phases without passing automated gate checks |
+| 🎯 **6 presets** | Full, Rapid, Debug, Architecture, Refactoring, Audit councils |
+| 📐 **Lean orchestrator** | Orchestrator uses ~10-15% context — delegates deep work to specialists |
+| 🧠 **Memory Module** | Deep intelligence layer: schemas, routes, services, components, tech stack |
+
 **What makes it different:**
 - ✅ **Real subagent spawning** — each agent gets a fresh 200k context via `Task()`, no context pollution
 - ✅ **13 deterministic CLI commands** — `council start`, `council next`, `council status`, etc.
@@ -72,6 +75,11 @@ ALENA now ships a local PRD creation path for teams that want product clarificat
 
 ## 🔄 Version History
 
+### 1.2.1 — Improve `/lmf` for manual coding
+
+- Update `lmf` so it remains learning-first but also includes copyable code blocks when implementation detail is needed.
+- Position `/lmf` as the manual-coding alternative to `/execute` when the user wants to type the code themselves instead of having the agent apply it automatically.
+
 ### 1.2.0 — Add `/prd` command
 
 - Add `write-prd` skill. Add `/prd` command for Claude Code and Antigravity.
@@ -133,6 +141,22 @@ npx @radenadri/skills-alena list
 
 After installing skills, your workflow depends on whether you're starting fresh or joining an existing codebase.
 
+### First question: do you need a PRD?
+
+If you only have an idea, a product problem, or a rough feature request, start with `/prd` before engineering planning.
+
+- `/prd` clarifies the user, problem, goals, non-goals, constraints, and success metrics.
+- `/discuss` locks implementation preferences and trade-off decisions before planning.
+- `/plan` turns the approved PRD or clarified request into implementation work.
+
+Think of it as:
+
+```text
+/prd = what and why
+/discuss = preference and trade-off lock-in
+/plan = how to build it
+```
+
 ### 🟢 New Project (Greenfield)
 
 > You're building something from scratch. No existing code, no legacy decisions.
@@ -141,6 +165,10 @@ After installing skills, your workflow depends on whether you're starting fresh
 ┌─────────────────────────────────────────────────────────────────┐
 │  GREENFIELD WORKFLOW                                            │
 │                                                                 │
+│  Step 0 ─ /prd (optional)                                       │
+│           Use when the project or feature idea is still fuzzy    │
+│           Produces a product requirements document first         │
+│                          ▼                                      │
 │  Step 1 ─ /init-project                                         │
 │           Creates .planning/ structure, ROADMAP, REQUIREMENTS    │
 │           Bootstraps memory system + config.json                 │
@@ -171,10 +199,13 @@ After installing skills, your workflow depends on whether you're starting fresh
 # 1. Install skills
 npx @radenadri/skills-alena add
 
-# 2. Tell your AI agent:
+# 2. If the product idea is still fuzzy, start here:
+/prd "describe the product or feature idea"
+
+# 3. Then tell your AI agent:
 /init-project
 
-# 3. The agent will walk you through:
+# 4. The agent will walk you through:
 #    → Project context gathering
 #    → Requirements capture
 #    → Roadmap phases
@@ -198,20 +229,24 @@ npx @radenadri/skills-alena add
 │           Writes: MEMORY.md with project brain                   │
 │           Captures: architecture, conventions, known issues      │
 │                          ▼                                      │
-│  Step 3 ─ /discuss                                              │
+│  Step 3 ─ /prd (optional)                                       │
+│           Use for new feature work that needs product clarity    │
+│           Grounds the PRD in the real codebase constraints       │
+│                          ▼                                      │
+│  Step 4 ─ /discuss                                              │
 │           "I want to add [feature] to this existing project"     │
 │           Agent asks MCQ questions considering existing patterns  │
 │           Quick-answer: "1A 2B 3C 4A"                           │
 │                          ▼                                      │
-│  Step 4 ─ /plan                                                 │
+│  Step 5 ─ /plan                                                 │
 │           Creates plan that respects existing architecture       │
 │           References real files, real patterns, real conventions  │
 │                          ▼                                      │
-│  Step 5 ─ /execute                                              │
+│  Step 6 ─ /execute                                              │
 │           Implements following existing patterns                 │
 │           codebase-conformity skill ensures consistency           │
 │                          ▼                                      │
-│  Step 6 ─ /verify                                               │
+│  Step 7 ─ /verify                                               │
 │           Validates against plan + existing test suite            │
 └─────────────────────────────────────────────────────────────────┘
 ```
@@ -224,10 +259,15 @@ npx @radenadri/skills-alena add
 # 2. Tell your AI agent:
 /memory init
 
-# 3. Let the agent scan your codebase, then:
+# 3. Let the agent scan your codebase
+
+# 4. If the feature needs product clarification, do this next:
+/prd "describe the feature or product problem"
+
+# 5. Then lock implementation decisions:
 /discuss add user preferences feature
 
-# 4. Answer the MCQ questions, then:
+# 6. Answer the MCQ questions, then:
 /plan
 /execute
 ```
@@ -319,7 +359,7 @@ Skills are deep instructional documents that teach AI agents HOW to think about
 |:---:|:---|:---|
 | 1 | 💡 **brainstorming** | Creative ideation — mind maps, structured exploration, and divergent thinking before any feature work |
 | 2 | 📄 **write-prd** | Product requirements writing — interview-first wrapper skill that turns feature ideas into structured PRDs before engineering planning — ✨ NEW |
-| 3 | 🧭 **lmf** | Learning-first mode flow — wrapper skill that combines `brainstorming`, `writing-plans`, and `writing-documentation` into a tutorial-first orchestration pattern — ✨ NEW |
+| 3 | 🧭 **lmf** | Learning-first mode flow — wrapper skill that combines `brainstorming`, `writing-plans`, and `writing-documentation` into a tutorial-first orchestration pattern with copyable code when manual implementation is needed — ✨ NEW |
 | 4 | 📝 **writing-plans** | Task decomposition — dependency-aware plans with effort estimates, risk assessments, and implementation waves |
 | 5 | ⚙️ **executing-plans** | Plan execution — wave-based implementation with checkpoints, inline verification, and state tracking |
 | 6 | 🧪 **test-driven-development** | TDD methodology — red-green-refactor cycle, test architecture, fixture patterns, and coverage strategies |
@@ -396,7 +436,7 @@ Commands are Claude Code slash commands (`.md` files installed to `.claude/comma
 | `/init-project` | 🏗️ Initialize a new project with `.planning/` directory — `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json`. Uses `planning-tools.cjs` for deterministic bootstrapping. |
 | `/discuss` | 💬 Pre-planning MCQ decision capture — presents multiple-choice questions with recommendations, quick-answer format (`1A 2B 3C`), locks decisions in CONTEXT.md |
 | `/prd` | 📄 Product requirements drafting — interview-first flow that uses the local `write-prd` wrapper skill to produce a reusable PRD before implementation planning — ✨ NEW |
-| `/lmf` | 🧭 Learning-first tutorial flow — uses the local `lmf` wrapper skill to combine explanation, planning, and documentation-style guidance before execution — ✨ NEW |
+| `/lmf` | 🧭 Learning-first tutorial flow — uses the local `lmf` wrapper skill to combine explanation, planning, and copyable code guidance before execution — ✨ NEW |
 | `/plan` | 📋 Create a 2-3 task implementation plan with task anatomy (`<files>` `<action>` `<verify>` `<done>`), context budgets, and locked decision enforcement |
 | `/execute` | ⚙️ Execute an implementation plan with deviation protocol (4 categories), checkpoint system, and `planning-tools.cjs` state management |
 | `/verify` | ✅ Validate implementations against plans — automated checks, compliance verification, regression testing, conversational UAT |
@@ -476,7 +516,7 @@ Workflows are Antigravity step-by-step execution scripts (`.md` files installed
 | `/init-project` | 🏗️ Initialize project with `.planning/` structure |
 | `/discuss` | 💬 Pre-planning MCQ discussion with quick-answer |
 | `/prd` | 📄 Product requirements workflow that mirrors the local `write-prd` wrapper skill in Antigravity — ✨ NEW |
-| `/lmf` | 🧭 Learning-first tutorial workflow that mirrors the local `lmf` wrapper skill in Antigravity — ✨ NEW |
+| `/lmf` | 🧭 Learning-first tutorial workflow that mirrors the local `lmf` wrapper skill in Antigravity, including copyable code when implementation is needed — ✨ NEW |
 | `/plan-feature` | 📋 Plan a feature with research, design, and task decomposition |
 | `/execute` | ⚙️ Execute plans with wave-based steps and verification |
 | `/verify` | ✅ Validate implementation against plans |
@@ -650,45 +690,6 @@ Use `/memory init` to initialize, `/memory write` to save.
 
 ---
 
-## 💎 LLM Council v2 — Agent Team Coordination
-
-### The Problem
-AI coding tasks fail at scale because no single agent can hold all context: database schemas, API routes, service dependencies, frontend components, and business logic — simultaneously. Linear handoffs lose context. Role-switching in a single context window wastes tokens.
-
-### The Solution: Real Subagent Spawning + Deterministic Orchestration
-
-**Council v2** replaces the old role-switching pattern with **real subagent spawning** via `Task()`. Each specialist agent gets a fresh 200k context window — no shared context pollution. The orchestrator stays lean at ~10-15% context usage.
-
-```
-                    ╔═══════════════════════════════╗
-                    ║     🎯 ORCHESTRATOR (lean)      ║
-                    ║  ~10-15% context usage           ║
-                    ║  13 deterministic CLI commands    ║
-                    ║  Code-enforced quality gates      ║
-                    ╚════════════╦══════════════════╝
-                                 ║
-                        Task() spawning
-              ┌──────────────────┼──────────────────┐
-       ┌──────▼──┐ ┌──────▼──┐ ┌──▼────┐ ┌──▼──────┐
-       │🔬Research│ │📐Planner│ │⚙️Exec │ │🔍Review │
-       │ Fresh    │ │ Fresh   │ │ Fresh │ │ Fresh   │
-       │ 200k ctx │ │ 200k   │ │ 200k  │ │ 200k   │
-       └──────────┘ └────────┘ └──────┘ └─────────┘
-```
-
-### Key Capabilities
-
-| Capability | Description |
-|:---|:---|
-| 🧠 **Real subagent spawning** | Each agent gets a fresh 200k context via `Task()` — no shared context pollution |
-| 🎛️ **13 CLI commands** | Deterministic state machine for council orchestration (`council start`, `council next`, `council status`, etc.) |
-| 🚪 **Code-enforced quality gates** | Agents cannot advance phases without passing automated gate checks |
-| 🎯 **6 presets** | Full, Rapid, Debug, Architecture, Refactoring, Audit councils |
-| 📐 **Lean orchestrator** | Orchestrator uses ~10-15% context — delegates deep work to specialists |
-| 🧠 **Memory Module** | Deep intelligence layer: schemas, routes, services, components, tech stack |
-
----
-
 ## 📁 Project Structure
 
 ```

package/commands/lmf.md

@@ -1,6 +1,6 @@
 ---
 name: lmf
-description: "Run the learning-first /lmf flow for tutorial-style planning and explanation before execution."
+description: "Run the learning-first /lmf flow for tutorial-style planning, explanation, and copyable code before execution."
 disable-model-invocation: true
 argument-hint: "[topic-or-task]"
 ---
@@ -18,6 +18,7 @@ Guide the user through the request in a tutorial-first way using the local `lmf`
    - Mental model
    - Recommended path
    - Step-by-step actions
+   - Copyable code
    - Next move
 4. Compose the existing ALENA skills inside the response:
    - `brainstorming` for intent and trade-offs
@@ -26,11 +27,13 @@ Guide the user through the request in a tutorial-first way using the local `lmf`
 5. Keep the output local-first and tutorial-first:
    - Explain before optimizing
    - Be specific to the current request and codebase
-   - Use small examples only when they reduce ambiguity
+   - Include copyable code blocks when the user needs to implement manually or when code would teach faster than prose
+   - Prefer complete file-level snippets over pseudo-code and placeholders
    - Do not turn `/lmf` into a shell-script or helper-script instruction
 
 ## Success Criteria
 
 - The user understands the problem shape before seeing the steps
 - The response contains a clear recommendation with trade-offs
+- The response includes copyable code when implementation detail is needed
 - The next action is explicit enough to execute immediately

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radenadri/skills-alena",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "ALENA is a personal toolkit for autonomous, networked AI agents",
   "author": {
     "name": "Adriana Eka Prayudha",
@@ -82,4 +82,4 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0"
   }
-}
+}

package/skills/lmf/SKILL.md

@@ -9,6 +9,8 @@ description: "Use when the user wants a learning-first walkthrough, tutorial-sty
 
 This skill turns a request into a tutorial-first response that teaches the user what is happening before pushing them straight into implementation. It wraps `brainstorming`, `writing-plans`, and `writing-documentation` into one repeatable flow so `/lmf` can stay educational without becoming vague.
 
+`/lmf` is also the manual-coding alternative to `/execute`: it should explain the work, show the shape of the implementation, and include copyable code blocks when code would help the user type the solution themselves instead of having the agent apply it automatically.
+
 **Core principle:** Teach the mental model first, then the implementation path, then the concrete next action.
 
 ## The Iron Law
@@ -24,6 +26,7 @@ WHEN /LMF IS ACTIVE, EXPLAIN THE MENTAL MODEL BEFORE PRESCRIBING THE STEPS.
 - The user wants explanation-heavy guidance for planning or documentation work
 - The user needs to understand the "why" and "how" before they start coding
 - The task benefits from combining design clarification, actionable planning, and reader-friendly documentation
+- The user wants to implement the code manually and needs copyable code output instead of automatic execution
 
 ## When NOT to Use
 
@@ -44,18 +47,21 @@ YOU CANNOT:
 - Turn /lmf into a helper-script instruction -- it must work through direct agent output
 - Overwhelm the user with exhaustive theory when a shorter explanation would teach faster
 - Claim the user is "ready to implement" without giving concrete next actions
+- Omit copyable code when the user clearly needs to type the implementation by hand
+- Use placeholder snippets, ellipses, or pseudo-code where real code is needed to teach the implementation
 ```
 
 ## Common Rationalizations (Don't Accept These)
 
 | Rationalization | Reality |
 |----------------|---------|
-| "They asked for help, so I'll just give them the final code" | /lmf exists to teach before it ships code. |
+| "They asked for help, so I'll just give them the final code" | /lmf exists to teach before it ships code, not to avoid code entirely. |
 | "The concepts are obvious" | If they invoked /lmf, the concepts are not obvious enough yet. |
 | "I'll explain after the steps" | Once the user is buried in steps, the teaching value is lost. |
 | "A long theory dump is more educational" | Good teaching is selective, not bloated. |
 | "The wrapper skill can just point to other skills" | A wrapper that does not synthesize is not doing its job. |
 | "This request is too practical for tutorial mode" | Practical requests are exactly where explanation-first guidance matters. |
+| "If I include code, it stops being /lmf" | /lmf should include code when the code helps the user learn and implement manually. |
 
 ## Iron Questions
 
@@ -68,7 +74,7 @@ YOU CANNOT:
 6. What are the first concrete actions the user can take after reading this? (list them)
 7. Did I teach the "why" before the "do this" instructions? (show the section order)
 8. Did I keep the explanation specific to the request instead of generic tutorial filler? (prove it)
-9. If I included code, does each snippet clarify a concept instead of replacing the explanation? (justify it)
+9. If I included code, does each snippet clarify a concept and give the user something real to type? (justify it)
 10. Can the user act on this output immediately without needing another translation step? (state how)
 ```
 
@@ -97,7 +103,8 @@ YOU CANNOT:
 1. EXPLAIN the mental model first -- what this is, why it matters, and how to think about it.
 2. GIVE the recommended approach second -- what path to take and why this path wins.
 3. BREAK the work into concrete steps third -- ordered, actionable, and scoped.
-4. INCLUDE examples only when they reduce ambiguity or teach a non-obvious concept faster.
+4. INCLUDE code when it reduces ambiguity, teaches a non-obvious concept faster, or lets the user implement the change manually.
+5. WHEN code is needed, prefer complete, copyable code blocks over pseudo-code or placeholder fragments.
 ```
 
 ### Phase 4: Land the Next Action
@@ -106,6 +113,7 @@ YOU CANNOT:
 1. END with the exact next move the user can take.
 2. IF implementation is requested, bridge cleanly into execution instead of repeating the lesson.
 3. IF documentation is requested, leave the user with wording or structure they can directly adopt.
+4. IF the user wants to code manually, give them the exact files and code blocks they can type in themselves.
 ```
 
 ## Output Format
@@ -129,16 +137,27 @@ Use this structure unless the user asks for a different shape:
 2. [Concrete action]
 3. [Concrete action]
 
+## Copyable Code
+[Only include when code is needed to implement or clarify the request.
+Prefer complete fenced blocks per file, with file names and no placeholder ellipses.]
+
 ## Next Move
 [Immediate follow-up action]
 ```
 
+When the request is implementation-oriented, `/lmf` should usually include a `Copyable Code` section after the explanation. The section should:
+- name the file being created or edited
+- provide complete, typeable code blocks for the core implementation
+- avoid placeholders like `...`, `TODO`, or "fill this in"
+- stay scoped to the minimum useful code that teaches the solution
+
 ## Red Flags -- STOP
 
 - Opening with implementation steps before explaining the shape of the task
 - Writing a generic tutorial that could apply to any repository
 - Giving only theory with no next action
 - Giving only steps with no explanation
+- Giving only file instructions with no actual code when code is necessary to complete the task manually
 - Using `/lmf` as a synonym for `/plan` or `/doc` without the learning-first layer
 - Treating the wrapper skill as a duplicate copy of the underlying skills
 

package/workflows/lmf.md

@@ -1,5 +1,5 @@
 ---
-description: Run the learning-first /lmf flow for tutorial-style explanation, planning, and documentation-oriented guidance
+description: Run the learning-first /lmf flow for tutorial-style explanation, planning, and copyable code guidance
 ---
 
 ## Steps
@@ -28,12 +28,14 @@ rg -n "$ARGUMENTS|lmf|tutorial|plan|README|CLAUDE|GEMINI" . --glob '!node_module
    - **Mental Model** - how to think about the task
    - **Recommended Path** - what to do and why
    - **Step-by-Step** - concrete actions in order
+   - **Copyable Code** - complete code blocks for the files the user may type manually when code is needed
    - **Next Move** - the immediate follow-up action
 
 6. Keep `/lmf` tutorial-first:
    - Explain before prescribing
    - Stay local-first and grounded in the current repo
-   - Use examples only when they teach faster than prose
+   - Include copyable code when it teaches faster than prose or when the user wants to implement manually
+   - Avoid placeholder snippets, pseudo-code, or "fill this in later" examples
    - Do not delegate to a local helper script
 
 7. If the user wants to move from teaching mode to implementation, bridge cleanly into `/plan`, `/execute`, or direct execution as appropriate.