--- name: genesis-development description: > This skill should be used when developing, debugging, refactoring, or building Genesis itself — tasks like "fix this in Genesis", "add a new MCP tool", "wire up the runtime", "Genesis won't start", "create a worktree", "debug the bridge", or "add a capability". Applies to any task modifying files under src/, .claude/, or tests/. Do NOT load for Genesis-as-tool work ("summarize this", "write a LinkedIn post", "research X") or general questions unrelated to Genesis internals. consumer: cc_foreground phase: 10 skill_type: workflow --- ## Load Gate Before reading any reference, confirm the task is Genesis-*development*, not Genesis-*as-tool*. If uncertain, ask the user: "Are we modifying Genesis itself, or using Genesis for something else?" ## On-Load Mindset Internalize these immediately when this skill fires — they shape how to work from the start, not just what to check before commit. ### Wiring Discipline Every new component needs at least one call site in the actual runtime path. Apply this 4-level verification taxonomy: 1. **Exists** — file/function present. Proves nothing. 2. **Substantive** — tests pass, handles happy + error. No runtime proof. 3. **Wired** — live call site, import chain unbroken. Minimum for "done." 4. **Data-Flow Verified** — real data flows end-to-end. Required for critical paths. Mark nothing "done" below Level 3. ### GROUNDWORK Code Is NOT Dead Code Code tagged `# GROUNDWORK(feature-id): why` is intentional future investment. Never delete or refactor it as dead code. Only remove when the feature is fully active or the user explicitly cancels it. ### Architecture Review For medium-to-large Genesis work (3+ files, new components, wiring changes), dispatch a `genesis-architect` subagent before implementation to check dependencies, edge cases, and DRY violations. Small targeted changes skip this. ### Timeout Policy The burden of proof is on you to justify why a timeout should exist. Do not default to "add a timeout for safety." Instead: 1. **Identify the specific failure mode.** What hangs? Why? Is there evidence this actually happens, or is it speculative? 2. **Justify the specific value.** Why this number and not another? What legitimate work would be killed at a lower value? 3. **If you have no strong justification for a specific value, default to 2 hours (7200s).** This is the project floor — generous enough to never interfere with legitimate work while preventing permanent resource lockout from truly hung processes. 4. **Surface the request to the user** with the value, the failure mode, and the evidence. Never add a timeout as a "small improvement" or "defense in depth." Timeouts on reflections, CC calls, cognitive paths, and long-thinking work fight Genesis instead of helping it — they cap legitimate long thinking and add speculative defense against rare hangs. The exception is raw subprocess calls with no external watchdog (e.g., deterministic executor steps), where a hung process blocks shared resources (executor semaphore) with no other recovery mechanism. ### Verify Outcomes, Not Just Tests `ruff check . && pytest -v` is the minimum bar, not the finish line. After tests pass, verify the actual end-to-end outcome the change delivers. Diff behavior between main and your changes when relevant. For wiring changes: verify the init/bootstrap order passes the right values at runtime, not just that parameters exist. For notification changes: verify the notification actually arrives. Ask: "If the system restarts right now, will this actually work?" If you can't answer yes with evidence, you're not done. ### Use GitNexus for Structural Code Intelligence GitNexus provides graph-based code intelligence that Grep/Serena cannot: multi-hop call chains, blast radius, execution flows, coupling analysis. **Before editing:** `gitnexus impact ` — check blast radius. Use full UID if ambiguous (e.g., `Method:path/file.py:Class.method#N`). **Before committing:** `gitnexus detect-changes` — verify you haven't missed dependent symbols. **Understanding unfamiliar code:** `gitnexus context ` for 360° view, or browse processes via `gitnexus://repo/GENesis-AGI/processes`. **Custom questions:** `gitnexus cypher` for raw graph queries. Note: LadybugDB uses `CodeRelation` with a `type` property for edges, not Neo4j-style named edge labels. Full syntax, Cypher examples, and decision matrix: `.claude/docs/code-intelligence-guide.md` ### Common Traps - **Ego sessions are ACTIVE.** `src/genesis/ego/` is live (v3.0a11). Two egos: user ego (CEO, Opus) and Genesis ego (COO, Sonnet). Both run on adaptive cadence via the awareness loop. Changes here are production changes. - **DB path confusion.** `genesis.db` is at `~/genesis/data/genesis.db`, NOT `~/genesis/genesis.db`. Use `genesis.env.genesis_db_path()`. - **Column names.** Use `db_schema` MCP before assuming column names. The DB has 60+ tables. - **Signal collectors.** Phase 1 built stubs; Phase 6 replaced some with real implementations. Code that looks complete may not produce signals. - **Capabilities manifest.** `~/.genesis/capabilities.json` is write-once at bootstrap, not dynamic. New capabilities need registration in `_CAPABILITY_DESCRIPTIONS` in `src/genesis/runtime/_capabilities.py` AND a bootstrap init step. - **APScheduler IntervalTrigger resets on restart.** `IntervalTrigger` counts from server startup, not from last successful run. If the server restarts more frequently than the interval, the job never fires. Use `CronTrigger` for anything longer than a few hours. Bit us with `user_model_evolution` (48h interval, daily restarts). ### Anti-Rationalization These are excuses sessions use to skip discipline. If you catch yourself thinking any of these, STOP — you are rationalizing a shortcut. | Rationalization | Why it's wrong | |---|---| | "This is just a simple fix, no tests needed" | Simple fixes break complex systems. The Qdrant regression was a "simple fix." Write the test. | | "I already know what this function does" | You haven't read the implementation. Docstrings lie. Read the actual code. | | "Tests pass, so we're done" | Tests verify what they cover, not the outcome. Verify actual end-to-end behavior. | | "I'll clean this up in the next commit" | Next commit never comes in autonomous sessions. Do it now or create a follow-up. | | "This file is too large to read fully" | Read the relevant section. Partial reads lead to partial understanding and wrong fixes. | | "The linter is happy, ship it" | Linters catch syntax, not logic. Clean lint with broken behavior is worse than a warning with correct behavior. | | "This change is low-risk, no impact analysis needed" | Your confidence is based on what you know. Impact analysis reveals what you don't. Run gitnexus impact. | | "I can skip the worktree, I'll be quick" | Concurrent session safety exists because "quick" commits have destroyed work before. Always worktree. | | "The error is transient, retry will fix it" | Diagnose first. Retrying a misdiagnosed error wastes tokens and masks root causes. | | "I'll add the follow-up later" | Follow-ups not created in-session are lost. Create it now while context is fresh. | | "I don't need a skill for this" | If a skill exists, use it. The using-superpowers Red Flags table exists for this exact rationalization. | | "I can read the summary instead of the source" | Summaries lose context. If you're about to change code, read the code, not the description of it. | ### Code Discovery Use the right tool for how you're exploring: - **Architecture overview** — CBM `get_architecture(aspects=["overview"])` - **Finding symbols** — CBM `search_graph(name_pattern="...")` or Serena `find_symbol` - **Call tracing** — CBM `trace_path(function_name="...")` or Serena `find_referencing_symbols` - **Impact before changes** — GitNexus `impact(path="...")` - **Config/doc/non-code files** — Grep/Read directly Full decision matrix: `.claude/docs/code-intelligence.md` ## Adaptive Review Protocol Choose the review level proportional to the change: | Change type | Review level | Examples | |---|---|---| | Docs / text / comments | **None** | Markdown prose, inline comments | | Simple mechanical | **None** | Variable rename, typo fix, import reorder | | Small focused fix | **Code-reviewer agent inline** | Single-function bug fix, config tweak | | Substantial change | **Code-reviewer inline + /review** | Multi-file refactor, new MCP tool, wiring | | Prompt / LLM behavior | **Both + extra scrutiny** | System prompts, skill instructions, routing | Decision criteria when ambiguous: "If the change could break a runtime path not covered by its own unit test, it needs /review. If it only touches things with clear, isolated test coverage, code-reviewer inline is sufficient." The enforcement hooks (`review_enforcement_prompt.py`, `review_enforcement_commit.py`) still fire on every change — they are safety nets, not the decision-maker. This protocol provides the judgment framework. ## Pre-Commit Gate Verify before any commit: - `git diff --cached --stat` — every file in the diff belongs to your work - `git status --short` — check untracked files (should be staged or ignored) - Review level applied matches the adaptive protocol above - Staged files do not include secrets (`secrets.env`, `.env`, credentials) - GROUNDWORK-tagged code not accidentally deleted - New capabilities registered in `_capabilities.py` + bootstrap manifest - **Conventional commit prefixes**: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`. Scope optional: `feat(ego): add cadence manager`. Subject line under 72 characters. Dominant category wins if mixed. - **NEVER push to main or merge into main without a PR and user approval.** Enforced by PreToolUse hook. - **Targeted tests during development.** Run ONLY the relevant test file(s) for your changes. NEVER run the full test suite locally — CI handles that. Check CI via `gh pr checks`. Bare `pytest` without a file path is banned. - **Commit continuously**: after every logical unit of work. Uncommitted = lost. ## Reference Router Read references ONLY when relevant to the specific task. Do NOT load all references on every trigger. | When you need... | Read... | |---|---| | Codebase structure, package map, gotchas, debugging | `references/codebase-map.md` | | Package/module/symbol navigation (progressive drill) | `codebase_navigate` MCP tool (L0→L1→L2) | | venv, DB paths, Qdrant, Ollama, network, commands | `references/environment.md` | | Worktree rules, concurrent sessions, branch naming | `references/worktrees.md` | | tracked_task, exc_info, os.killpg, logging patterns | `references/observability.md` | | V3 state, build order, GROUNDWORK, architecture docs | `references/architecture.md` | | Phase 6 contribution pipeline, sanitizer | `references/contribution.md` | | Pending work, active incidents, subsystem status | `references/build-state.md` | | Which code tool to use (CBM vs Serena vs GitNexus vs Grep) | `.claude/docs/code-intelligence.md` | **Freshness rule:** On first read of `codebase-map.md` in a session, verify structural claims against current code. If a package status or gotcha has changed, flag to user before acting on stale assumptions. ## Public Repo & Release Workflow The public repo (`GENesis-AGI`) is the primary development repo. Standard open-source workflow: PRs go directly to the public repo. - **Squash merges only** — merge commits are disabled on the public repo. Always `git pull --rebase origin main` after merging a PR before committing locally, or push will be rejected (non-fast-forward). - **README is public-authoritative** — the public repo's `README.md` is hand-crafted and must NEVER be overwritten. - **CHANGELOG audience is users** — only include entries a user updating their install would care about. No internal refactors, README changes, CI tweaks, or process artifacts. Lead with the user-visible effect, not the implementation technique. - **No sensitive data in commits** — voice data, research profiles, IPs, and secrets must never enter the repo. User data lives in overlays outside the repo (e.g., `~/.claude/skills/*/`, `~/.genesis/`).