Why Commands?

Claude Code and Codex read your codebase, edit files, run commands, and spawn sub-agents on their own. Hyprlayer’s skills and agents sit on top of that.

What the Base Tools Already Do

• Claude Code ships built-in sub-agents (Explore, Plan, general-purpose), auto-memory across sessions (MEMORY.md), and runs git commands, creates commits, and opens PRs.
• Codex is OpenAI’s CLI, with its own plan mode, sub-agents, and git operations.

Both read your code, make multi-file edits, run tests, and iterate on failures. Ask one of them to rename a variable and it will. Skip the commands.

Non-trivial work exposes the gaps.

What Commands Add

Enforced Phase Separation

Ask any of these tools to “build feature X” and they start writing code. They read a few files first, then research, planning, and implementation blur into a single pass. You never see a plan before the code lands.

• /research_codebase documents and nothing else. It describes what exists, where it lives, and how it works. It will not suggest improvements, critique the code, or propose changes unless you ask for that. Left to themselves, both tools editorialize.
• /create_plan produces a plan: phased steps, specific file changes, success criteria, checkboxes. It writes no code. Hyprlayer instructs the agent to be skeptical, so it challenges your assumptions and names the risks instead of agreeing with you.
• /implement_plan takes a plan file path and follows the spec. It reads the plan and every referenced file, hands each substantial phase to a foreman sub-agent in a fresh context, re-runs the phase’s verification itself, and ticks the plan’s checkboxes. It stops and asks when the plan and the code disagree.

Base tools let you ask for a plan first. Nothing stops the model from jumping ahead, and you get no artifact to carry into the next phase.

A Persistent, Shared Knowledge Base

Claude Code reads CLAUDE.md for project instructions and keeps auto-memory for facts like “this project uses pnpm.” Neither base tool gives your team a structured, shared knowledge system.

The thoughts directory is a shared store of research, plans, PR descriptions, and handoffs, backed by git, an Obsidian vault, Notion, or Anytype, organized by project and searchable by AI agents.

• /research_codebase writes findings to thoughts/shared/research/ (or a typed row on notion/anytype). Next session, the research is still there, and a teammate’s session reads it too.
• /create_plan saves plans to thoughts/shared/plans/YYYY-MM-DD-description.md. Your team reviews them asynchronously, refines them with /iterate_plan, and cites them months later.
• /describe_pr reads a PR template from thoughts/shared/pr_description.md and saves the generated description to thoughts/shared/prs/. Every PR lands with the same structure.
• /create_handoff compacts the current session’s context into a document at thoughts/shared/handoffs/. A new session picks it up with /resume_handoff and continues where you left off.

Post-commit hooks sync the repository after each code commit, and the searchable index (thoughts/searchable/) gives agents flat access to everything.

CLAUDE.md and session memory are per-developer and unstructured. The thoughts store is shared across your team, and commands read and write it on their own.

Specialized Sub-Agents with Focused Roles

Claude Code’s built-in sub-agents are generic. Explore is a fast, read-only codebase searcher. Plan does read-only research. Useful, but neither knows your domain.

Hyprlayer installs nineteen agents. Ten are stage agents that carry one step of the pipeline (cartographer, draughtsman, adjudicator, foreman, inspector, quartermaster, herald, marshal, adversarial-reviewer, archivist); the rest are narrow research workers:

• codebase-locator finds files and components relevant to a task. Describe what you want in English and it locates the code, rather than matching strings.
• codebase-analyzer works out how a specific piece of code behaves, down to the implementation.
• codebase-pattern-finder surfaces similar implementations already in your codebase. It returns concrete code from the API endpoints you have, so the one you add matches them.
• thoughts-locator and thoughts-analyzer search the thoughts directory and surface prior research, existing plans, and history the base tools don’t know exists.
• web-search-researcher searches the web for API documentation and library usage patterns that live outside your codebase.
• jira-ticket-reader and jira-searcher pull ticket details from JIRA and find related issues.

/research_codebase breaks the question into areas, spawns one cartographer per area in parallel alongside an archivist for the prior paper trail, and reaches for a codebase-* agent only for a single narrow lookup, then synthesizes one document.

Base-tool agents know nothing about your thoughts directory, your JIRA instance, or the patterns in your code.

Per-Command Model Selection

You run whatever model your session started with. Claude Code uses the model in your settings. Switching means stopping to switch.

Commands pin their own models:

• Opus for /create_plan and /iterate_plan, and for the agents that judge rather than gather: draughtsman, adjudicator, marshal, adversarial-reviewer.
• Sonnet for /research_codebase, /implement_plan, /commit, /describe_pr, and every research agent.
• The remaining commands inherit whatever model your session is running.

Opus and Sonnet have different strengths. Opus produces more thorough analysis during planning and review, and Sonnet turns research and implementation cycles around faster. Where a command pins a model, it picks for you.

Behavioral Constraints You’d Forget to Specify

Models agree with your approach, add “Co-Authored-By” lines to commits, suggest improvements when you asked for documentation, and implement things their own way when a plan exists.

Commands encode the corrections:

• /research_codebase documents what exists and withholds the improvement suggestions the model wants to volunteer.
• /create_plan challenges your assumptions and names the risks. Models default to agreement; this command overrides that.
• /commit adds no AI attribution: no “Co-Authored-By,” no “Generated with,” no “AI-assisted.” Imperative mood, focused on why rather than what, specific file paths instead of git add -A or git add ., and your approval before anything lands.
• /implement_plan reads every file the plan references, verifies success criteria after each phase, updates the checkboxes, and reports deviations rather than papering over them.
• /validate_plan checks every success criterion, reports pass or fail on each, and flags deviations, missing implementations, and regressions, drawing evidence from diffs, test results, and codebase state.
• /describe_pr reads your team’s PR template, fills out every section, asks whether to run the verification commands the template lists, ticks only what actually passed, and updates the PR with gh pr edit.
• /founder_mode cherry-picks the commit to a new branch, creates a JIRA ticket, and opens a PR, dragging finished work back into the team’s process.

You could type all of this at the start of a conversation. Six exchanges later the model has drifted and you’ve stopped repeating yourself. Commands hold the constraints for the whole session.

Session Continuity Across Context Limits

A long session fills its context window. Start a new one and you lose the last one. Claude Code’s auto-memory keeps some preferences and none of your working state.

• /create_handoff compacts your session into a structured document: what you finished, what’s left, the decisions you made, the files you touched, the blockers you hit. It lands in thoughts/shared/handoffs/.
• /resume_handoff reads that document, restores context by reading every file it references, and picks up where the previous session stopped.

The model remembers nothing here. One session writes a document describing its working state, the next session reads it, and neither base tool ships anything equivalent.

Git Workflow Opinions

Both tools run git commands without an opinion about how to use git. They commit everything with git add ., write generic messages, and open PRs against no template.

• /commit reviews the changes, groups related files into atomic commits, drafts messages in imperative mood focused on why, and shows you the plan before running anything. It passes specific paths to git add, never -A or ., and never adds AI attribution.
• /describe_pr reads your team’s PR template from the thoughts directory, analyzes the full diff and commit history, asks whether to run the verification the template calls for (make check test, say), fills every section, saves the result to thoughts, and updates the PR on GitHub.
• /local_review sets up a git worktree for a colleague’s branch. It resolves the PR number to a branch name, extracts ticket info, creates the worktree under ~/hyprlayer/worktrees/<repo>/<short-name> on a review/<branch> branch, copies your local Claude settings, installs dependencies, initializes thoughts there, and hands you the path to open a session in.

Cross-Session, Cross-Tool Portability

Claude Code reads skills from ~/.claude/skills/ and agents from ~/.claude/agents/; Codex reads its agents from ~/.codex/agents/. Switch tools and you start over.

Hyprlayer installs the same skills and agents for Claude Code and Codex (hyprlayer ai status shows both; hyprlayer ai reinstall repairs them), and the thoughts store doesn’t care which one wrote to it. Plan a feature in Claude Code, implement it in Codex. Write a handoff in one tool, resume it in another.

When to Skip Commands

Reach for the base tool when:

• You have a one-off question. “What does this function do?” doesn’t need /research_codebase.
• The change is small. Renaming a variable or fixing a typo doesn’t need a plan.
• You want to think out loud before committing to a structure.

Anything that spans more than one sitting is worth the structure.