🌟 What is This?

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.

💎 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 |

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.
• ✅ Code-enforced quality gates — agents cannot advance phases without passing automated checks
• ✅ 6 presets — Full, Rapid, Debug, Architecture, Refactoring, Audit
• ✅ Lean orchestrator — stays at ~10-15% context, delegates deep work to specialists
• ✅ Zero infrastructure — pure file-based, works in ANY agent environment

🔄 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.

1.1.0 — Add /lmf command

• Add lmf skills. Add /lmf command for Claude Code and Antigravity.

1.0.0 — Initial ALENA Release

• 🧠 ALENA identity and public release reset — the toolkit starts at v1.0.0 with ALENA branding, updated install commands, refreshed docs, and release surfaces aligned under the new package and repository.
• 🤖 Full asset library included — ships with 35 skills, 36 commands, 39 workflows, and 9 specialist agents covering brainstorming, planning, PRD creation, execution, debugging, auditing, review, verification, memory, and team coordination.
• ⚙️ Deterministic planning core — planning-tools.cjs plus 12 supporting CLI modules handle state, phase, roadmap, verification, frontmatter, config, templates, milestones, model resolution, and council coordination without relying on brittle freeform markdown edits.
• 🏛️ Council system built in — real subagent spawning, structured handoffs, code-enforced quality gates, task boards, and 6 presets (full, rapid, debug, architecture, refactoring, audit) are included in the first release.
• 🪝 Hook and session tooling — includes 8 hooks for statusline, update checks, context monitoring, memory capture, cost tracking, and related session behavior where the target runtime supports them.
• 📝 Templates and rules layer — includes 11 templates plus the core ruleset for anti-hallucination behavior, severity reporting, memory discipline, and evidence-based verification.
• 🌐 Cross-agent portability — installation and generated entrypoint content support 34+ AI coding agents, with native directory/layout handling across Claude Code, Cursor, Windsurf, Gemini/Antigravity, Copilot, Codex, and more.
• 💾 File-based memory and planning state — .planning/ artifacts, manifests, and markdown state keep the toolkit portable, inspectable, and repository-friendly without requiring external infrastructure.
• 🧪 Publishable CLI package — the release includes the npm package identity, built dist/cli.js entrypoint, scoped GitHub Packages support, and documentation aligned to the 1.0.0 ALENA release line.

🚀 Quick Start

Install globally (recommended)

npx @radenadri/skills-alena add

This auto-detects your installed agents and installs everything — skills, commands, workflows, agents, and rules — to the right directories.

In 1.0.0, hooks such as security-gate, statusline, and context-monitor are registered automatically during installation. Run /team to start a multi-agent council session.

Install to a specific agent

npx @radenadri/skills-alena add --agent claude-code
npx @radenadri/skills-alena add --agent cursor
npx @radenadri/skills-alena add --agent antigravity

Install specific skills only

npx @radenadri/skills-alena add persistent-memory agent-team-coordination
npx @radenadri/skills-alena add code-review systematic-debugging

See everything available

npx @radenadri/skills-alena list

🏁 Getting Started — Greenfield vs Brownfield

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:

/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.

┌─────────────────────────────────────────────────────────────────┐
│  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                 │
│           (Uses: node planning-tools.cjs init)                   │
│                          ▼                                      │
│  Step 2 ─ /discuss                                              │
│           Multiple-choice questions with recommendations         │
│           Quick-answer: "1A 2B 3C 4A 5A"                        │
│           Locks decisions in CONTEXT.md                          │
│                          ▼                                      │
│  Step 3 ─ /plan                                                 │
│           Creates 2-3 task plan respecting locked decisions      │
│           Each task has <files> <action> <verify> <done>         │
│                          ▼                                      │
│  Step 4 ─ /execute                                              │
│           Task-by-task execution with checkpoints                │
│           Deviation protocol for plan changes                    │
│           State tracked by planning-tools.cjs                    │
│                          ▼                                      │
│  Step 5 ─ /verify                                               │
│           Validates implementation against the plan              │
│           Gap closure if anything was missed                     │
└─────────────────────────────────────────────────────────────────┘

Quick start for greenfield:

# 1. Install skills
npx @radenadri/skills-alena add

# 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

# 4. The agent will walk you through:
#    → Project context gathering
#    → Requirements capture
#    → Roadmap phases
#    → Then suggest /discuss to lock decisions

🟡 Existing Codebase (Brownfield)

You're joining a project that already has code, patterns, and decisions. The AI needs to learn the codebase BEFORE making changes.

┌─────────────────────────────────────────────────────────────────┐
│  BROWNFIELD WORKFLOW                                            │
│                                                                 │
│  Step 1 ─ /memory init                                          │
│           Creates .planning/ structure for the existing project  │
│           (Uses: node planning-tools.cjs init)                   │
│                          ▼                                      │
│  Step 2 ─ Codebase Mapping (automatic)                          │
│           Agent scans: file structure, patterns, tech stack      │
│           Writes: MEMORY.md with project brain                   │
│           Captures: architecture, conventions, known issues      │
│                          ▼                                      │
│  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 5 ─ /plan                                                 │
│           Creates plan that respects existing architecture       │
│           References real files, real patterns, real conventions  │
│                          ▼                                      │
│  Step 6 ─ /execute                                              │
│           Implements following existing patterns                 │
│           codebase-conformity skill ensures consistency           │
│                          ▼                                      │
│  Step 7 ─ /verify                                               │
│           Validates against plan + existing test suite            │
└─────────────────────────────────────────────────────────────────┘

Quick start for brownfield:

# 1. Install skills into your existing project
npx @radenadri/skills-alena add

# 2. Tell your AI agent:
/memory init

# 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

# 6. Answer the MCQ questions, then:
/plan
/execute

Key Differences

| | 🟢 Greenfield | 🟡 Brownfield | |:---|:---|:---| | First step | /init-project (full setup) | /memory init (lightweight) | | Context source | Your answers to questions | Codebase scanning → MEMORY.md | | Patterns | You define them | Agent discovers existing patterns | | Planning | Free to choose any approach | Must respect existing architecture | | Risk | Low (no breaking changes) | Higher (must be compatible) | | Skills activated | writing-plans, executing-plans | + codebase-mapping, codebase-conformity |

The /discuss Quick-Answer Format

When the agent presents multiple-choice questions, you can answer everything in one line:

### ⚡ Quick Answer

> All recommended: 1A 2B 3A 4B 5A
>
> Your answer: 1A 2B 3C 4A 5:"use Redis for sessions"

| Format | Meaning | |:---|:---| | 1A | Question 1, Option A | | 2B | Question 2, Option B | | 5:"custom text" | Question 5, Custom answer | | Just press Enter | Accept all recommendations |

🏗️ Supported Agents

ALENA works with 30+ AI coding agents. 12 platforms have full asset parity (Claude Code, Copilot, Codex, Cursor, Windsurf, Cline, Roo, Amp, Augment, Continue, Kilo, Goose). Each agent gets assets installed to its native directory:

| | Agent | Skills | Commands | Workflows | Rules | |:---:|:---|:---:|:---:|:---:|:---:| | | Claude Code | .claude/skills/ | .claude/commands/ | — | — | | | Cursor | .cursor/skills/ | — | — | .cursor/rules/ | | | Antigravity (Gemini) | .agent/skills/ | — | .agent/workflows/ | — | | | Gemini CLI | .gemini/skills/ | — | — | — | | | GitHub Copilot | .github/skills/ | — | — | — | | | Windsurf | .windsurf/skills/ | — | — | — | | | Cline | .cline/skills/ | — | — | — | | | Roo | .roo/skills/ | — | — | — | | | Codex | .agents/skills/ | — | — | — | | | Amp | .agents/skills/ | — | — | — | | | Kilo Code | .kilocode/skills/ | — | — | — | | | Augment | .augment/skills/ | — | — | — | | | Continue | .continue/skills/ | — | — | — | | | Goose | .goose/skills/ | — | — | — | | | OpenCode | .agents/skills/ | — | — | — | | | Trae | .trae/skills/ | — | — | — | | | Junie | .junie/skills/ | — | — | — | | | OpenClaw | skills/ | — | — | — | | | OpenHands | .openhands/skills/ | — | — | — | | | Kode | .kode/skills/ | — | — | — | | | Qoder | .qoder/skills/ | — | — | — | | | Mux | .mux/skills/ | — | — | — | | | Zencoder | .zencoder/skills/ | — | — | — | | | Crush | .crush/skills/ | — | — | — | | | Droid | .factory/skills/ | — | — | — | | | Command Code | .commandcode/skills/ | — | — | — | | | CodeBuddy | .codebuddy/skills/ | — | — | — | | | Mistral Vibe | .vibe/skills/ | — | — | — | | | Qwen Code | .qwen/skills/ | — | — | — | | | Pi | .pi/skills/ | — | — | — | | | Replit | .agents/skills/ | — | — | — | | | Kiro CLI | .kiro/skills/ | — | — | — | | | iFlow CLI | .iflow/skills/ | — | — | — | | | Kimi CLI | .agents/skills/ | — | — | — |

📚 Complete Asset Catalog

🧠 Skills (35)

Skills are deep instructional documents that teach AI agents HOW to think about specific engineering tasks. Each skill contains principles, protocols, anti-patterns, and quality criteria.

🔷 Core Development (10 skills)

| # | Skill | Description | |:---:|:---|:---| | 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 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 | | 7 | 🐛 systematic-debugging | Scientific debugging — hypothesis-driven investigation with evidence chains and root cause analysis | | 8 | 🔍 code-review | Structured code review — security, performance, correctness checks with severity-based feedback | | 9 | ✅ verification-before-completion | Completion gates — automated checks, compliance verification, and regression testing before marking done | | 10 | 📦 git-workflow | Git best practices — conventional commits, branching strategies, PR workflows, and conflict resolution |

🔶 Auditing (10 skills)

| # | Skill | Description | |:---:|:---|:---| | 11 | 🏛️ architecture-audit | Architecture review — modularity, coupling, SOLID compliance, dependency direction, and scalability assessment | | 12 | 🔒 security-audit | Security assessment — OWASP top 10, auth flows, input validation, secrets management, and vulnerability scanning | | 13 | ⚡ performance-audit | Performance profiling — N+1 queries, bundle sizes, runtime bottlenecks, caching opportunities, and load testing | | 14 | 🗄️ database-audit | Database health — schema design, indexing strategy, query optimization, migrations, and normalization review | | 15 | 🎨 frontend-audit | Frontend quality — component architecture, state management, rendering efficiency, and responsive design | | 16 | 🌐 api-design-audit | API design review — REST/GraphQL conventions, versioning, error handling, pagination, and documentation | | 17 | 📦 dependency-audit | Dependency health — outdated packages, security vulnerabilities, license compliance, and bundle impact | | 18 | 📊 observability-audit | Observability review — logging strategy, metrics, tracing, alerting, and production debugging capability | | 19 | ♿ accessibility-audit | Accessibility compliance — WCAG standards, keyboard navigation, screen reader support, and color contrast | | 20 | 🔄 ci-cd-audit | CI/CD pipeline review — build times, test reliability, deployment safety, and pipeline optimization |

🔷 Evolution (4 skills)

| # | Skill | Description | |:---:|:---|:---| | 21 | ♻️ refactoring-safely | Safe refactoring — incremental transformation with test coverage, feature flags, and rollback strategies | | 22 | 📖 writing-documentation | Documentation authoring — API docs, architecture diagrams, README standards, and knowledge transfer | | 23 | 🗺️ codebase-mapping | Codebase analysis — module boundaries, dependency graphs, entry points, and health metrics | | 24 | 🚨 incident-response | Incident handling — triage protocols, root cause analysis, post-mortems, and prevention measures |

🟣 Agent Intelligence (2 skills)

| # | Skill | Description | |:---:|:---|:---| | 25 | 💾 persistent-memory | Automated session memory — captures decisions, context, and learnings across sessions via file-based protocols. Zero infrastructure, works in ANY agent. Inspired by claude-mem. | | 26 | 💎 agent-team-coordination | LLM Council — Manager-orchestrated multi-agent coordination with Memory Module. Manager has full project knowledge (schemas, routes, services), dynamically routes tasks to specialist sub-agents, enables peer communication, handles escalations across 6 council presets. |

🔶 Integration & Completeness (4 skills)

| # | Skill | Description | |:---:|:---|:---| | 27 | 🔗 full-stack-api-integration | End-to-end API integration — spec analysis, surface mapping, SOLID-compliant API layer design, systematic endpoint implementation, and integration testing | | 28 | 🏥 product-completeness-audit | Functional completeness verification — 5-level completeness spectrum, placeholder detection, broken flow identification, and API connection validation | | 29 | 🔬 brutal-exhaustive-audit | No-shortcuts 5-pass audit — build verification, route checking, data flow tracing, user flow testing, and edge case validation with anti-shortcut rules | | 30 | 🔄 codebase-conformity | Pattern uniformity enforcement — read existing patterns before writing, match them exactly, and double-verify conformity before claiming done |

🔀 Migration (1 skill)

| # | Skill | Description | |:---:|:---|:---| | 31 | 🔀 nextjs-to-nuxt-migration | Next.js → Nuxt 4 migration — submodule analysis, backend verification, multi-pass execution (backend wiring → feature completeness → CSS polish → verification), sidebar registration, theme/dark-mode rules, URL encoding, Agent Team File Protocol, and Playwright visual QA |

🔸 Meta (5 skills)

| # | Skill | Description | |:---:|:---|:---| | 32 | 📘 using-skills | How to use and combine skills effectively in your workflow | | 33 | ✍️ writing-skills | How to create new skills — format, quality standards, and testing requirements | | 34 | 🎨 ui-ux-redesign | Full-stack visual audit — inventories backend APIs, audits every component and design token, analyzes user flows, and produces layered redesign recommendations | | 35 | 📏 _rules | Master rules skill — consolidates core principles, anti-hallucination protocol, severity framework, and skill activation table |

⚡ Commands (36)

Commands are Claude Code slash commands (.md files installed to .claude/commands/). They provide structured workflows for common project tasks.

🔷 Project Lifecycle

| Command | Description | |:---|:---| | /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 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 | | /progress | 📊 Display project progress, phase status, and task completion from .planning/ state files | | /settings | ⚙️ View/modify project config — mode (interactive/auto), depth (quick/standard/comprehensive), workflow preferences |

🔷 Research & Documentation

| Command | Description | |:---|:---| | /research | 🔬 Deep research on topics before planning — generates structured reports in .planning/research/ | | /doc | 📖 Generate documentation for code, APIs, architecture, or setup | | /explain | 💡 Provide detailed explanations of code, architecture, or concepts |

🔷 Code Quality

| Command | Description | |:---|:---| | /review | 🔍 Structured code review with severity-based feedback (critical/major/minor/nit) | | /test | 🧪 Generate and run tests — unit, integration, e2e with coverage reporting | | /debug | 🐛 Scientific debugging with hypothesis tracking and evidence chains | | /fix-issue | 🔧 Diagnose and fix specific issues with minimal changes and regression testing | | /refactor | ♻️ Safe refactoring with test coverage and incremental transformation |

🔷 Operations & Security

| Command | Description | |:---|:---| | /migrate | 🗄️ Database or code migrations with safety checks, rollback strategies, and data validation | | /performance | ⚡ Profile and analyze application performance with benchmarking | | /security-scan | 🔒 Comprehensive security scan — OWASP top 10, secrets detection, dependency vulnerabilities | | /deploy-check | 🚀 Pre-deployment validation checklist | | /audit | 📋 Full codebase audit — linting, secrets, console logs, TODOs |

🔷 Workflow

| Command | Description | |:---|:---| | /quick | ⚡ Execute small, well-defined tasks without full project planning | | /commit | 📦 Create well-formatted Conventional Commits with proper scope and body |

🟣 Agent Intelligence

| Command | Description | |:---|:---| | /memory | 💾 Persistent memory management — init, read, write, compress, status operations | | /team | 🤝 Multi-role team coordination — start, resume, next, board, status operations |

🔶 Integration & Auditing

| Command | Description | |:---|:---| | /integrate | 🔗 Full-stack API integration from spec — surface mapping, SOLID architecture, endpoint implementation, and verification | | /health-check | 🏥 Product completeness audit — route inventory, placeholder detection, flow testing, and API connection checks | | /deep-audit | 🔬 Brutal exhaustive 5-pass audit — build, routes, data flow, user flows, and edge cases with anti-shortcut rules | | /redesign | 🎨 Full UI/UX redesign audit — visual audit, component census, token extraction, UX analysis, layered redesign plan |

🟡 Intelligence & Orchestration

| Command | Description | |:---|:---| | /learn | 📚 Extract reusable patterns from sessions across 8 categories with deduplication, persisted to .planning/LEARNINGS.md | | /quality-gate | ✅ 6-step quality pipeline (Build → Type Check → Lint → Test → Security → Diff) with 4 modes: quick, full, pre-commit, pre-pr | | /checkpoint | 📍 Named progress snapshots with create/verify/list modes stored in .planning/checkpoints/ | | /loop | 🔁 Bounded loop execution — repetitive tasks with safety bounds (max iterations, stall detection, test-between-iterations) | | /orchestrate | 🔗 Multi-agent orchestration — chain agents in predefined sequences (feature, bugfix, refactor, security) with structured handoffs | | /context | 🎯 Context mode switching — dev (code-first), research (read-widely), review (quality-first) modes that change workflow behavior |

🔄 Workflows (39)

Workflows are Antigravity step-by-step execution scripts (.md files installed to .agent/workflows/). Many include // turbo annotations for auto-execution.

| Workflow | Description | |:---|:---| | /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, 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 | | /research | 🔬 Deep research with structured report output | | /progress | 📊 Display project status and completion | | /quick | ⚡ Quick task execution without full planning | | /debug | 🐛 Scientific debugging workflow | | /fix-issue | 🔧 Issue diagnosis and fix | | /review | 🔍 Structured code review | | /test | 🧪 Test generation and execution | | /refactor | ♻️ Safe refactoring with tests | | /commit | 📦 Conventional commit creation | | /doc | 📖 Documentation generation | | /explain | 💡 Code explanation | | /audit | 📋 Codebase audit | | /security-scan | 🔒 Security scanning | | /performance | ⚡ Performance profiling | | /migrate | 🗄️ Database/code migration | | /deploy-check | 🚀 Deployment validation | | /release | 🏷️ Release preparation | | /codebase-map | 🗺️ Codebase analysis and mapping | | /deps-update | 📦 Dependency updates | | /incident-response | 🚨 Incident triage and response | | /memory-sync | 💾 Memory read/write/compress operations | | /team-session | 🤝 Multi-role team coordination | | /integrate-api | 🔗 Full-stack API integration workflow | | /product-health-check | 🏥 Product completeness audit workflow | | /deep-audit | 🔬 Brutal exhaustive audit workflow | | /redesign | 🎨 Full UI/UX redesign workflow | | /gap-closure | 🔧 Close execution gaps with focused mini-plans |

🤖 Agents (9)

Agent definitions are specialist AI personas (.md files installed to .claude/agents/). Each agent has detailed protocols, principles, and anti-patterns.

| Agent | Emoji | Description | |:---|:---:|:---| | researcher | 🔬 | Deep codebase and domain research — gathers comprehensive evidence and context before planning. Emphasizes accuracy, exhaustive search, and source attribution. | | planner | 📋 | Plans-as-prompts — generates dependency-aware plans with task anatomy (<files> <action> <verify> <done>), context budgets, locked decision enforcement, and multi-plan sequencing. | | executor | ⚙️ | Plan execution with deviation protocol — implements tasks with checkpoint handling (standard/context/blocker), DON'T/AVOID instruction enforcement, and planning-tools.cjs state management. | | reviewer | 🔍 | Structured code review — examines changes for correctness, security, performance, patterns, and maintainability. Provides severity-based feedback. | | debugger | 🐛 | Scientific debugging with hypothesis tracking — investigates issues using hypothesis-driven methodology with evidence chains and persistent state. | | verifier | ✅ | Work verification and gap analysis — validates implementation against plans, runs comprehensive checks, identifies gaps, and generates fix plans. | | mapper | 🗺️ | Codebase mapping and dependency analysis — analyzes project structure, module boundaries, dependencies, patterns, and health metrics. | | investigator | 🕵️ | Deep investigation for Debug Council — forensic analysis of complex bugs with evidence chains and timeline reconstruction. | | fixer | 🔧 | Targeted fix implementation for Debug Council — minimal, surgical fixes with regression prevention and rollback strategies. |

🎯 Cursor Rules (10)

Cursor rules are .mdc files installed to .cursor/rules/. They guide Cursor AI's behavior for specific concerns.

| Rule | Description | |:---|:---| | 🏗️ core-development | Code quality standards — SOLID principles, DRY, error handling, testing, and Git commit conventions | | 🚫 anti-hallucination | Anti-fabrication protocol — mandates verification of APIs, paths, configs before use. Prevents hallucinated code. | | 📋 planning-workflow | Structured planning — research → design → decompose → estimate → document workflow | | 🐛 debugging-protocol | Scientific debugging — hypothesis → test → evidence → root cause methodology | | 🔒 security | Security best practices — auth, input validation, data handling, secrets management | | 🗄️ database | Database rules — schema design, indexing, query optimization, migrations | | 🧪 testing | Testing standards — coverage requirements, fixture patterns, assertion quality | | 🔍 code-review | Code review checklist — automated and manual review criteria | | 💾 memory-protocol | Persistent memory — auto-read MEMORY.md on start, auto-write on end | | 🤝 team-protocol | Team coordination — sequential role-switching with blackboard |

📏 Rules (5)

Universal rules (.md files) that can be appended to GEMINI.md, CLAUDE.md, or any agent's system prompt.

| Rule | Description | |:---|:---| | 🏗️ core-principles | Foundational engineering principles — SOLID, DRY, KISS, YAGNI, and clean architecture | | 🚫 anti-hallucination | Verification-first protocol — never fabricate APIs, paths, or configs | | ⚖️ severity-framework | Issue severity classification — critical/major/minor/nit with response criteria | | 💾 memory-protocol | Persistent memory instructions — auto-read and auto-write .planning/MEMORY.md | | 🤝 team-protocol | Team coordination instructions — role-switching and blackboard protocol |

💾 Persistent Memory + State Management

The Problem

Every AI session starts from scratch. You explain the same architecture, repeat the same decisions, and lose context.

The Solution

File-based memory protocol + deterministic state management — no hooks, no databases, no external services. Works in ANY agent.

.planning/
├── MEMORY.md                    # 🧠 Project brain (~300 lines max)
├── STATE.md                     # 📍 Current position (phase/plan/task)
├── config.json                  # ⚙️ Mode, depth, preferences
├── sessions/                    # 📝 Session logs
├── decisions/DECISIONS.md       # 📋 Decision log (append-only)
├── plans/                       # 📋 Implementation plans
├── research/                    # 🔬 Research + CONTEXT.md from /discuss
├── context/
│   ├── architecture.md          # 🏗️ Architecture decisions
│   ├── patterns.md              # 🔄 Established patterns
│   ├── gotchas.md               # ⚠️ Known issues
│   └── tech-debt.md             # 🔧 Technical debt
└── handoffs/LATEST.md           # 📤 Last session's handoff

planning-tools.cjs — Deterministic State Management

LLMs are unreliable at structured file operations. The planning-tools.cjs CLI handles these deterministically:

# Bootstrap the .planning/ directory
node planning-tools.cjs init

# Track execution progress
node planning-tools.cjs state load              # Where am I?
node planning-tools.cjs state advance-task      # Mark task complete
node planning-tools.cjs state add-decision      # Record a decision
node planning-tools.cjs state add-blocker       # Flag a blocker

# Manage configuration
node planning-tools.cjs config get mode         # interactive or auto?
node planning-tools.cjs config set depth comprehensive

# Validate and report
node planning-tools.cjs verify structure        # Is .planning/ intact?
node planning-tools.cjs progress                # Show dashboard

How Memory Works

SESSION START                    DURING SESSION                  SESSION END
┌────────────────────┐           ┌────────────────────────┐      ┌────────────────────┐
│ 1. Read MEMORY.md  │           │ 4. planning-tools.cjs  │      │ 8. Create session  │
│ 2. Read LATEST.md  │           │    tracks state changes│      │    log              │
│ 3. Read config.json│           │ 5. Decisions → log     │      │ 9. Write handoff   │
│    Full context!   │           │ 6. Blockers → flag     │      │ 10. Update memory  │
└────────────────────┘           └────────────────────────┘      └────────────────────┘

Setup

For Antigravity

Add to ~/.gemini/GEMINI.md:

## 🧠 Automatic Memory Protocol
ALWAYS at the START: read .planning/MEMORY.md and .planning/handoffs/LATEST.md
ALWAYS at the END: update MEMORY.md, write handoffs/LATEST.md

For Cursor

Install the memory-protocol.mdc rule (auto-installed with npx @radenadri/skills-alena add).

For Claude Code

Use /memory init to initialize, /memory write to save.

Comparison with claude-mem

| | claude-mem | ALENA | |:---|:---:|:---:| | Infrastructure | SQLite + Chroma + Bun | Zero ✅ | | Agent support | Claude Code only | ANY agent ✅ | | State management | None | planning-tools.cjs CLI ✅ | | Capture method | Lifecycle hooks | Instruction-based | | Storage | Database | Markdown files (git!) | | Setup | Plugin install + config | Add 4 lines to GEMINI.md |

📁 Project Structure

alena/
├── 📂 skills/                   # 35 deep instructional skills
│   ├── brainstorming/SKILL.md
│   ├── writing-plans/SKILL.md          # Plans-as-prompts with task anatomy
│   ├── executing-plans/SKILL.md        # Deviation protocol + checkpoints
│   ├── persistent-memory/SKILL.md
│   ├── agent-team-coordination/SKILL.md
│   └── ... (26 more)
├── 📂 commands/                 # 36 Claude Code slash commands
│   ├── init-project.md
│   ├── discuss.md                       ✨ MCQ decision capture
│   ├── settings.md                      ✨ Config management
│   ├── memory.md
│   ├── team.md
│   └── ... (23 more)
├── 📂 workflows/                # 39 Antigravity workflows
│   ├── init-project.md
│   ├── discuss.md                       ✨ MCQ discussion workflow
│   ├── gap-closure.md                   ✨ Execution gap closure
│   ├── memory-sync.md
│   ├── team-session.md
│   └── ... (27 more)
├── 📂 agents/                   # 9 specialist agent definitions
│   ├── planner.md                       # Plans-as-prompts, locked decisions
│   ├── executor.md                      # Deviation protocol, context awareness
│   ├── investigator.md                  # Debug Council forensics
│   ├── fixer.md                         # Debug Council surgical fixes
│   └── ... (5 more)
├── 📂 scripts/                  # Deterministic tooling
│   └── planning-tools.cjs              # State management CLI
├── 📂 cursor-rules/             # 10 Cursor .mdc rules
│   ├── core-development.mdc
│   ├── memory-protocol.mdc
│   └── ... (8 more)
├── 📂 rules/                    # 5 universal agent rules
│   ├── core-principles.md               # + Context Engineering principle
│   ├── memory-protocol.md              # + planning-tools.cjs integration
│   └── ... (3 more)
├── 📂 docs/                     # Documentation
├── 📂 src/                      # CLI source
│   └── cli.ts
├── CLAUDE.md                    # Claude Code integration
├── GEMINI.md                    # Gemini/Antigravity integration
├── package.json
└── README.md                    # You are here!

🛠️ CLI Reference

Commands

# Install everything (auto-detect agents)
npx @radenadri/skills-alena add

# Install to specific agent
npx @radenadri/skills-alena add --agent antigravity
npx @radenadri/skills-alena add --agent cursor
npx @radenadri/skills-alena add --agent claude-code

# Install globally (available in all projects)
npx @radenadri/skills-alena add --global

# Install specific skills
npx @radenadri/skills-alena add persistent-memory code-review
npx @radenadri/skills-alena add lmf brainstorming writing-plans writing-documentation
npx @radenadri/skills-alena add write-prd brainstorming writing-documentation

# Update all skills to latest version
npx @radenadri/skills-alena update

# Show installation status and version
npx @radenadri/skills-alena status

# List all available assets
npx @radenadri/skills-alena list

# Show supported agents
npx @radenadri/skills-alena agents

# Non-interactive install (CI/CD friendly)
npx @radenadri/skills-alena add --all -y -a '*'

# Show help
npx @radenadri/skills-alena help

Flags

| Flag | Description | |:---|:---| | -a, --agent <name> | Install to a specific agent (use '*' for all) | | -g, --global | Install globally (user home) instead of project | | --all | Install all available skills | | -y, --yes | Non-interactive mode (auto-accept) | | --help | Show help text |

Install Behavior

| Asset | Local Install | Global Install (-g) | |:---|:---|:---| | Skills | Copied to agent dir. Re-running updates existing. | Copied to global agent dir. | | Commands | Copied to .claude/commands/ | ❌ Skipped | | Workflows | Copied to .agent/workflows/ | ❌ Skipped | | Agent Defs | Copied to .claude/agents/ | ❌ Skipped | | Cursor Rules | Copied to .cursor/rules/ | ❌ Skipped | | CLAUDE.md | Appends activation section (preserves your content). Updates on re-install. | ❌ Skipped | | GEMINI.md | Appends activation section (preserves your content). Updates on re-install. | ❌ Skipped | | Memory | Never installed (created at runtime per-project). | ❌ Never installed |

If you want the full local experience, install locally so wrapper skills can be paired with their agent-specific surfaces. That applies to both lmf and PRD drafting: global install includes the lmf and write-prd skills, but the Claude Code /lmf and /prd commands plus the Antigravity /lmf and /prd workflows are local-only surfaces.

What Gets Installed Where

| Asset Type | Claude Code | Cursor | Antigravity | |:---|:---|:---|:---| | Skills | .claude/skills/ | .cursor/skills/ | .agent/skills/ | | Commands | .claude/commands/ | — | — | | Workflows | — | — | .agent/workflows/ | | Agent Defs | .claude/agents/ | — | — | | Rules | — | .cursor/rules/ | — |

📖 Documentation

| Document | Description | |:---|:---| | 🌐 Website | Product homepage and primary landing page | | 📖 Wiki | Comprehensive GitHub Wiki with guides and reference | | skills/write-prd/SKILL.md | Local wrapper skill for interview-first PRD creation | | commands/prd.md | Claude Code /prd product requirements command | | workflows/prd.md | Antigravity /prd product requirements workflow | | skills/lmf/SKILL.md | Local wrapper skill for the lmf orchestrator pattern | | commands/lmf.md | Claude Code /lmf learning-first command | | workflows/lmf.md | Antigravity /lmf learning-first workflow | | Agent Teams & Memory | Comprehensive guide to the team coordination and persistent memory systems | | Competitive Analysis | Analysis of GSD, Claude Code, Cursor, and Antigravity frameworks | | Audit Report | Comprehensive quality audit report for the ALENA skill library | | Contributing | How to contribute to this project | | Changelog | Version history and release notes |

📊 By the Numbers

| Metric | Count | |:---:|:---:| | 🧠 Skills | 35 | | ⚡ Commands | 36 | | 🔄 Workflows | 39 | | 🤖 Agents | 9 | | 🎯 Cursor Rules | 10 | | 📏 Rules | 5 | | 🪝 Hooks | 8 | | 📦 CLI Modules | 13 | | 📐 Templates | 11 | | 📚 References | 2 | | 🎛️ Council Commands | 13 | | 🤖 Supported Agents | 34 |

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/radenadri/skills-alena.git

# Install dependencies
npm install

# Build
npm run build

# Test locally
node dist/cli.js list

🙏 Acknowledgments

This project stands on the shoulders of giants. Huge thanks to these projects that inspired and influenced the design of ALENA:

| | Project | Author | Contribution | |:---:|:---|:---|:---| | | Skills by Amrit | Amritpal Singh Boparai | Direct inspiration for ALENA's skills-driven structure, planning workflows, and multi-agent toolkit direction. | | | Superpowers | Jesse Vincent (@obra) | Pioneered the agentic skills framework concept — composable skills, TDD-first workflows, and subagent-driven development. The foundation we all build on. | | | GSD (Get Shit Done) | @glittercowboy | Spec-driven development with context rot prevention, parallel agent spawning, and executable plans. Showed how to keep AI agents focused and productive. | | | Agent Skills Standard | Anthropic | The open standard for packaging and sharing AI agent capabilities via SKILL.md files. | | | skills.sh | Community | The agent skills directory and CLI that makes skill discovery and installation universal. |

📄 License

MIT © Adriana Eka Prayudha. Original upstream copyright notice remains in LICENSE.