Specialized AI genies for product discovery and delivery, from opportunity mapping to spec-driven implementation.
Software teams face relentless pressure to deliver business outcomes while also building scalable systems. High costs, tight timelines, communication gaps, coordination overhead, and inconsistent practices across the team frame the challenges messy in the middle. AI coding agents promise help but often add noise; generating code without context, expanding scope without constraint, forgetting and drifting from decisions and guardrails already made.
What if your AI assistant was a team of specialists instead of one generalist? Genie Team brings industry practices, insight, and workflows to Claude Code. Curated wishes, focused expertise, and a document trail that builds shared understanding as things evolve over time. It's an experiment in whether structured AI collaboration can reduce friction, align practices, and help teams move faster without sacrificing craft and pride of ownership.
- Philosophy & Vision
- Install
- Bootstrap a New Project
- Bootstrap an Existing Project
- Working with Genie Team
- Local Dev, CI/CD & Deployment
- The Genies
- Commands & Skills
- Structure
- Inspiration & Credits
We're at an inflection point in how software gets made. AI assistants are powerful but unpredictable. They'll grant your wishes, just not always the way you intended. This project is an exploration: What if we could shape that power into something more deliberate?
Genie Team is a playground for discovering new ways of working. It's not a finished product but an ongoing harvesting of experiments in human-AI collaboration. This is an attempt to find patterns that make augmented development more effective, more sustainable, more intentional, more craft-oriented, and even a little fun.
Genies, not agents. AI coding assistants work best when you think of them as genies, powerful entities that grant wishes but interpret those wishes on their own terms. Without structure, they drift: expanding scope, losing context mid-session, and confidently building the wrong thing. Genie Team adds the constraints that make wishes reliable: specialized roles, scoped tools, structured prompts, and persistent context that survives the conversation window.
Team of specialists. Instead of one general purpose assistant, Genie Team provides a cast of specialized genies, each optimized for a specific phase of product development. Specialization beats generalization.
Context accumulates. Structured outputs (Opportunity Snapshots, Design Documents, Implementation Reports) create a document trail that builds project knowledge over time. Genie memory complements this with meta-learning: patterns noticed across sessions, calibrations, and shortcuts that help each genie work more effectively on your project.
Efficiency matters. AI tokens cost money and time. Structured prompts with clear scope reduce wasted iterations, hallucinated features, and context drift.
Tinkering as practice. This is exploratory work. Forking, adapting, and sharing configurations is part of our craft. The goal isn't to prescribe a workflow but to provide a starting point for your own experiments in augmented development.
- Claude Code CLI (v1.0.33+) — The foundation that genie-team extends
ghCLI (optional) — For PR creation in PR-mode workflowsjq(optional) — For the headless runner's JSON parsing
git clone git@github.com:elmmly/genie-team.git ~/genie-team
cd ~/genie-team
# Install globally (available to all projects)
./install.sh global
# Or install to a specific project
./install.sh project /path/to/your/project
# Verify installation
./install.sh statusGlobal install puts commands, genies, skills, and rules in ~/.claude/ so they're available across all projects. Best for individual developers or teams with consistent practices.
Project install puts everything in /path/to/project/.claude/ for isolation. Best for trying out the workflow or when different projects need different configurations.
Plugin Install (Experimental)
Note: Plugin install is experimental. The Claude Code plugin system is still evolving, and plugin installs may not include all components. The script install above is the recommended approach.
Install as a Claude Code plugin. Commands are namespaced as /genie:command (e.g., /genie:discover, /genie:deliver).
/plugin marketplace add elmmly/genie-team
/plugin install genie@genie-team --scope user
The plugin provides commands, genies, skills, hooks, and the MCP image generation server. Rules and schemas require a supplemental step:
git clone git@github.com:elmmly/genie-team.git ~/genie-team
cd ~/genie-team && ./install.sh global --rules --schemasStart a Claude session and load context:
cd /path/to/your/project
claude
> /context:loadThis scans for existing specs, ADRs, diagrams, and backlog items, then recommends next steps.
Plugin users: use
/genie:context:loadinstead (all commands are namespaced under/genie:).
| Component | Purpose |
|---|---|
| Commands | Slash commands (/discover, /deliver, etc.) |
| Genies | Specialist definitions with scoped tools and persistent memory |
| Skills | Automatic behaviors (TDD, code quality, brand awareness) |
| Hooks | Context re-injection on compaction |
| MCP | Image generation server (Designer genie via Gemini) |
| Rules | Always-on constraints (workflow, code quality, conventions) |
| Schemas | Document format definitions (ADR, spec, shaped contract) |
| Scripts | genies (headless runner + session management + quality checks) |
All script install options
./install.sh global # Full global install (includes MCP)
./install.sh global --commands # Commands only
./install.sh global --skills # Skills only (automatic behaviors)
./install.sh global --agents # Agents only
./install.sh global --rules # Rules only
./install.sh global --hooks # Hooks only (context re-injection)
./install.sh global --schemas # Schemas only
./install.sh global --scripts # Scripts only (genies)
./install.sh global --mcp # MCP server only (imagegen)
./install.sh project /path/to/app # Full project install
./install.sh project --skip-mcp # Everything except MCP
./install.sh project --force # Re-install/upgrade (overwrite existing)
./install.sh project --sync # Clean install (removes obsolete files)
./install.sh project --dry-run # Preview changes
./install.sh prehook /path/to/app # Install pre-commit hooks (standalone)
./install.sh uninstall # Remove genie-team installationStarting from scratch? Three steps set up your project — architecture, brand, then your first feature. The foundation workshops don't require any backlog items, so you can run them on day 1.
Establish the technical foundation — no shaped feature needed:
> /arch --workshop
The Architect genie leads a 5-phase interactive session:
- Approach Comparison — "What are we building?" then side-by-side HTML panels evaluating 2-3 system-level architectural alternatives
- Technical Decisions — Walk through each significant choice interactively (tech stack, database, deployment target, CI provider). Opens with "Which tech stack?" — selecting from available profiles (TypeScript, Go, Elixir, Rust, etc.)
- Interface Preview — System-level API boundaries between containers in code-styled HTML preview
- Risk Prioritization — Select which mitigations are worth the investment
- Consolidation — Workshop summary + ADRs for all decisions captured
Then initialize the project with the decisions from the workshop:
> /arch:init --stack elixir # Stack chosen in Phase 2
This generates the architecture artifacts and stack configuration in one step:
- C4 diagrams (
docs/architecture/) — System context and container diagrams - ADR-000 bootstrapping record + any ADRs from workshop decisions (
docs/decisions/) - Stack rules (
.claude/rules/stack-{language}.md) — Language-specific quality rules loaded every session - Build permissions (
.claude/settings.json) — Verification commands auto-permitted - Tech stack section in CLAUDE.md — Compact reference for the project
Result: Your project's technical foundation is set — stack, architecture diagrams, and decision records all in place.
Establish visual identity and design language:
> /brand --workshop
The Designer genie leads a 6-phase interactive workshop:
- Identity — Name, mission, voice, personality traits
- Colors — Palette exploration with generated HTML previews and accessibility validation
- Typography — Font families, scale, hierarchy with real-world scenario previews
- Imagery — Photography, illustration, and abstract style exploration with generated examples
- Target Examples — Brand north star images generated with Gemini
- Consolidation — Brand guide with W3C Design Tokens
Result: Your project's visual identity is set — brand guide (docs/brand/{name}-brand.md), design tokens (docs/brand/tokens.json), and generated visual examples ready for implementation.
Now that the foundation is set, shape concrete work:
> /discover "the problem we're solving"
> /define --workshop "the opportunity to pursue"
The Scout explores the problem space (opportunity mapping, assumptions, unknowns). Then the Shaper leads a 4-phase interactive session — problem framing, appetite sizing, option exploration, scope negotiation — producing a Shaped Work Contract (docs/backlog/P{N}-{topic}.md) and a capability spec (docs/specs/{domain}/{capability}.md).
Planned:
/discover --workshop— A structured multi-phase product discovery workshop with iteration loops, similar to the brand workshop. Today,/discoveris a single-pass command.
After the foundation workshops and first shaped feature, your project has:
docs/
├── analysis/ # Architecture workshop summary
├── architecture/ # C4 diagrams (system context, containers)
├── backlog/ # First feature shaped, ready for design
├── brand/ # Brand guide + design tokens
├── decisions/ # ADR-000 + workshop decisions
└── specs/ # Capability specs
.claude/
├── rules/stack-*.md # Language-specific quality rules
└── settings.json # Build/verification permissions
CLAUDE.md # Tech stack section
Ready to design and build:
> /arch --workshop docs/backlog/P1-first-feature.md # Design against the foundation
> /deliver docs/backlog/P1-first-feature.md
Joining an existing codebase? Genie Team can scan what's there and generate the missing artifacts.
> /spec:init
The Scout genie performs a deep scan of source code, tests, config files, and documentation. It identifies capabilities by behavioral grouping (not file structure), presents them in batches for you to assign domains, and generates specs with acceptance criteria inferred from tests.
> /arch:init
The Architect genie infers containers from directory structure, package.json workspaces, Dockerfiles, and config files. It detects external systems from database configs, API URLs, and service integrations. Output: C4 diagrams and an ADR-000 bootstrapping record.
For existing projects, /arch:init auto-detects the tech stack from indicator files (tsconfig.json, go.mod, Cargo.toml, mix.exs, etc.) and generates stack-specific quality rules and build permissions. No --stack flag needed — it reads what's already there.
> /diagnose
The Architect genie scans for:
- Dead code and pattern violations
- Coupling violations (undocumented cross-domain dependencies)
- ADR health (stale proposals, contradictory decisions)
- Diagram staleness (>90 days without update)
- Test coverage gaps (capabilities with tests but no specs)
Use the interactive workshops from Section 2 to address gaps that scanning alone can't fill:
> /define --workshop "area that needs product clarity"
> /arch --workshop docs/backlog/P2-area-needing-architecture.md
The 7 D's lifecycle — discover, define, design, deliver, discern, commit, done — can be run in different modes depending on the level of control you want.
Full lifecycle with manual gates at each transition. Best for learning the workflow or complex features where you want to steer at each phase.
> /feature "user authentication improvements"
Runs discover → define → design → deliver → discern, pausing for your approval at each transition. You can redirect, refine, or reject before the next phase begins.
Same phases, no manual gates. /discern is the automated quality gate — stops on BLOCKED, continues through APPROVED. Best for trusted execution of well-shaped work.
> /run "add password reset" # Full lifecycle from topic
> /run docs/backlog/P2-auth.md # Continue from backlog item
> /run docs/backlog/P2-auth.md --from design # Skip discovery + shaping
> /run --through define "explore notification patterns" # Just discover + define
Chains claude -p per phase for cron, CI/CD, or GitHub Actions. Best for daily discovery pipelines or overnight delivery. Available on PATH after global install.
# Full lifecycle from topic
genies "add password reset"
# Discovery pipeline — have the genies explore and shape improvement areas
genies --through define \
"identify 3-5 opportunities to improve the product UX" \
"identify 3-5 foundational improvements for reliability and performance" \
"identify 3-5 developer experience improvements"
# Implement approved items (run after human review)
genies --from design docs/backlog/P2-auth.md
# Deliver everything in the backlog while you're away from the keyboard
genies --parallel 3 --trunk --verbose --log-dir logs/overnight
# With operational flags
genies --lock --log-dir ./logs \
--from design docs/backlog/P2-auth.mdFeatures: phase ranges (--from/--through), lockfiles (--lock), per-phase turn limits, automatic retry on exhaustion, structured JSON logging (--log-dir), exit codes (0=success, 1=failure, 2=merge conflict, 3=validation error).
Use any command directly for surgical work:
> /deliver docs/backlog/P2-auth.md # Just implement
> /discern docs/backlog/P2-auth.md # Just review
> /commit docs/backlog/P2-auth.md # Just commit
Shortcuts for common patterns:
| Command | What It Does |
|---|---|
/bugfix "broken login" |
Light shape → deliver → discern |
/spike "can we use SQLite?" |
Time-boxed technical investigation |
/cleanup auth module |
diagnose → tidy (safe refactoring) |
Multiple genie-team sessions working on the same repo simultaneously via git worktrees:
# Start a parallel session
genies session start P2-search deliver
# → Creates ../myproject--P2-search on branch genie/P2-search-deliver
# List active sessions
genies session list
# Finish (push + PR, remove worktree)
genies session finish P2-search
# Or merge directly (trunk-based)
genies session finish P2-search --merge
# Or leave branch for later integration (used by parallel batch)
genies session finish P2-search --leave-branch
# Clean up all merged sessions
genies session cleanupEnable by adding worktree-enabled to your project's CLAUDE.md.
PR mode (default): Feature branches (genie/{item}-{phase}) with pull requests via gh. No direct pushes to main.
Trunk-based mode (opt-in): Direct commits to main. Activate by adding to your project's CLAUDE.md:
## Git Workflow
trunk-basedGenie Team's workshops capture infrastructure decisions, and the existing lifecycle delivers them.
The architecture workshop (/arch --workshop) captures infrastructure decisions as ADRs:
- Which container runtime (Docker, Podman, native)
- Which CI provider (GitHub Actions, CircleCI, GitLab CI)
- Which deployment target (AWS, Vercel, Fly.io, K8s)
- Which observability stack (Datadog, Grafana, CloudWatch)
These decisions live in docs/decisions/ADR-{NNN}-{slug}.md. Then use the normal lifecycle to implement them:
> /define "set up local dev environment with Docker"
> /deliver docs/backlog/P2-local-dev-setup.md
No special infrastructure command needed — the same workflow that builds features also builds infrastructure.
/arch:init documents the system in C4 diagrams showing containers, external systems, and deployment boundaries.
Run multiple items in parallel with serialized integration — all through genies:
# Deliver all actionable backlog items with 3 parallel workers, trunk-based
genies --parallel 3 --trunk --verbose \
--log-dir logs/overnight
# Deliver only P1 items (auto-detects phase from status)
genies --priority P1 --parallel 2 --trunk \
--verbose --log-dir logs/p1-delivery
# Have the genies discover and shape improvement areas in parallel
genies --parallel 3 --trunk --verbose \
--through define --log-dir logs/discovery \
"identify 3-5 ways to improve the onboarding experience" \
"identify 3-5 performance and reliability improvements" \
"identify 3-5 ways to reduce developer friction"
# Preview what would run (no execution)
genies --parallel 3 --dry-runParallel mode uses git worktrees for isolation. Workers leave branches intact after completing, then the runner serializes integration (rebase+ff for --trunk, push+PR otherwise). Logs in --log-dir for post-run inspection.
For CI/CD integration with genies:
# Nightly discovery pipeline — genies explore and shape improvement opportunities
0 2 * * * genies --through define --lock --log-dir ./logs \
"identify 3-5 opportunities to improve the product experience"
# Weekend delivery — genies work through the entire backlog while you're away
0 22 * * 5 genies --parallel 3 --trunk --lock --log-dir ./logs/weekend
# Implement specific approved items (manual trigger or CI)
genies --from design --lock --log-dir ./logs docs/backlog/P2-approved-item.md| Genie | Command | Purpose |
|---|---|---|
| Scout | /discover |
Discovery, research, opportunity mapping |
| Shaper | /define |
Problem framing, appetite, constraints |
| Architect | /arch, /design, /diagnose |
Technical design, patterns, health |
| Crafter | /deliver |
TDD implementation, code quality |
| Critic | /discern |
Review, acceptance criteria, risks |
| Tidier | /tidy |
Refactoring, cleanup, tech debt |
| Designer | /brand |
Brand identity, visual assets, design tokens |
Genie Team extends Claude Code using two complementary mechanisms:
Commands (.claude/commands/) — Explicit slash commands that you invoke. Each command activates a specific genie for a specific phase of the lifecycle.
Skills (.claude/skills/) — Automatic behaviors that activate based on context. No explicit invocation needed — Claude applies them when relevant.
Both are the recommended Claude Code extension patterns. Commands are for workflows you choose to run. Skills are for standards you always want enforced.
All commands
/discover [topic]— Explore a problem space/define [input]— Frame work with appetite and constraints (--workshopfor interactive)/arch [contract] --workshop— Interactive architecture workshop/design [contract]— Create technical design (batch)/deliver [design]— Implement with TDD/discern [impl]— Review and validate/commit [item]— Create conventional commit/done [item]— Archive completed work
/feature [topic]— Full lifecycle with manual gates/run [item]— Autonomous lifecycle (no gates, /discern as quality gate)/bugfix [issue]— Quick fix flow/spike [question]— Technical investigation/cleanup [scope]— Debt reduction
/brand [input]— Brand workshop (--workshopfor fresh,--evolveto update)/brand:image [prompt]— Generate brand-consistent image/brand:tokens [guide]— Extract W3C design tokens
/diagnose [scope]— Scan codebase health/tidy [report]— Execute safe cleanup
/spec:init [scope]— Generate specs from source code/arch:init— Generate architecture diagrams
/context:load— Initialize session/context:summary— End-of-session handoff/context:recall [topic]— Find past work/context:refresh— Update from codebase/handoff [from] [to]— Phase transition with context
/genie:help— Show all commands/genie:status— Show current work status
All skills (automatic behaviors)
| Skill | Activates When |
|---|---|
| tdd-discipline | Writing code, implementing features, fixing bugs |
| code-quality | Implementing features, editing code, refactoring |
| conventional-commits | Committing code, creating git commits |
| problem-first | Defining work, feature requests, "we should add..." |
| pattern-enforcement | Designing systems, reviewing code structure |
| spec-awareness | Loading context, starting features, discussing specs |
| architecture-awareness | Discussing architecture, ADRs, C4 diagrams |
| brand-awareness | Working with brand guides, design tokens, visual identity |
genie-team/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest (name, version, metadata)
│ └── marketplace.json # Marketplace catalog for /plugin install
├── commands/ # Slash command definitions
├── agents/ # Genie definitions
├── skills/ # Automatic behavior skills
├── hooks/
│ ├── hooks.json # Plugin hook configuration
│ ├── track-command.sh # Command tracking
│ ├── track-artifacts.sh # Artifact tracking
│ └── reinject-context.sh # Context re-injection on compaction
├── rules/ # Always-on constraints
├── schemas/ # Document format schemas
├── genies/ # Genie specs, system prompts, templates
├── scripts/
│ ├── genies # CLI entry point (lifecycle, session, quality)
│ ├── genie-session # Session library (sourced by genies)
│ └── validate/ # Quality validation scripts
├── templates/ # Project templates (CLAUDE.md)
├── tests/ # Test suite
└── install.sh # Installation script
Two complementary persistence systems:
| System | Purpose | Location | Lifecycle |
|---|---|---|---|
| Document trail | Project knowledge — findings, designs, reviews, decisions | docs/ (git-tracked) |
Created → appended → archived |
| Genie memory | Genie meta-learning — patterns, calibrations, shortcuts | .claude/agent-memory/ (gitignored) |
Curated continuously, 150-line cap |
Document trail stores what the project knows. Genie memory stores what each genie has learned about working on this project. Genies get better at your specific project over time.
This project draws heavily from the work of:
The "genie" framing for AI coding assistants comes from Beck's writing on his Tidy First? Substack where he explores a number of topics including augmented coding vs. "vibe coding." Key insights include treating AI as a genie that grants wishes literally (requiring precise requests), the importance of "exhaling" (tidying/refactoring) to counter the genie's tendency to only "inhale" (add features), and the seed corn problem of complexity accumulation.
- Tidy First?: A Personal Exercise in Empirical Software Design (O'Reilly, 2023)
- Augmented Coding & Design — The genie metaphor and complexity trap
- Augmented Coding: Beyond the Vibes — Vibe coding vs. augmented coding distinction
- Test-Driven Development, Extreme Programming, and simple design principles
Teresa Torres — Continuous Discovery Habits (2021). The Scout genie draws from her structured approach to continuous discovery: weekly customer touchpoints, opportunity mapping, assumption testing, and the Product Trio model. See producttalk.org.
Ryan Singer — Shape Up: Stop Running in Circles and Ship Work that Matters (Basecamp, 2019). The Shaper genie implements his appetite-driven approach: fixed time/variable scope, six-week cycles, pitches, and the betting table. Free online at basecamp.com/shapeup.
Clayton Christensen & Tony Ulwick — Jobs-to-be-Done framework. Christensen popularized JTBD in The Innovator's Solution (2003); Ulwick created the underlying Outcome-Driven Innovation methodology. See Jobs to be Done: Theory to Practice (Ulwick, 2016).
Marty Cagan — Inspired: How to Create Tech Products Customers Love (2nd ed, 2017) and Empowered: Ordinary People, Extraordinary Products (2020). The Shaper genie incorporates his product sense and empowered teams philosophy. See svpg.com.
Melissa Perri — Escaping the Build Trap: How Effective Product Management Creates Real Value (O'Reilly, 2018). Her outcome-over-output philosophy shapes the Shaper genie's focus on value over features.
Martin Fowler (ThoughtWorks) — Refactoring: Improving the Design of Existing Code (2nd ed, 2018). The Tidier and Crafter genies draw from his catalog of refactoring patterns. Online catalog at refactoring.com/catalog.
Dave Thomas & Andy Hunt — The Pragmatic Programmer (20th Anniversary Edition, 2019). The Crafter genie's practical, no-dogma approach to implementation draws from their emphasis on working software, continuous learning, and craftsmanship without ceremony.
Last updated: 2026-03-03