APPENDIX 8: ALIGNSTACK SLASH COMMANDS
What Are Slash Commands?
Slash commands are reusable prompts packaged as markdown files. In Claude Code, you type /command-name and the contents of the corresponding .md file get injected as a prompt — with your input substituted in.
They turn multi-paragraph prompts you’d otherwise type (or copy-paste) every time into one-word shortcuts. Each command is self-contained: one prompt in, one artifact out.
Slash commands live as .md files in a commands/ directory:
- Project-level:
.claude/commands/— available only in that project - Global:
~/.claude/commands/— available in every project
Installation
Install all AlignStack slash commands globally with one line:
curl -sL https://raw.githubusercontent.com/karaposu/alignstack/main/commands/install.sh | bash
This downloads all slash commands and hooks into ~/.claude/ so they’re available in every project you open with Claude Code.
To install for a single project only, copy the commands/ folder contents into .claude/commands/ in your project root.
Activating the devdocs metadata hook
The installer downloads the devdocs_metadata_appender.sh hook to ~/.claude/hooks/. To activate it, add this to your .claude/settings.json (project) or ~/.claude/settings.json (global):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/devdocs_metadata_appender.sh"
}
]
}
]
}
}
This automatically prepends a metadata header (date, branch, commit, author) to every file written under devdocs/. See Appendix 9 for the metadata format.
Core Commands
These four commands form the primary AlignStack workflow. Each produces an artifact that the next can consume, but all work independently.
/elaborate → /task-desc → /task-plan → /critic
/elaborate and /task-desc serve different purposes: /elaborate takes messy input and makes it readable — no structure imposed, just clarity. /task-desc takes that clear input and shapes it into a formal feature description with problem statement, success criteria, and scope. One tidies, the other structures for implementation.
/elaborate
Take messy, scattered input and make it tidy — structured, clear, and easy to read. Accepts raw text, file paths, images or all. Saves the output as markdown and flags important ambiguities.
The primary goal is clarity, not task analysis. Alignment verification is a side effect.
Input: Raw text, file path, or file path + additional text Output: Structured rephrasing saved as markdown + printed in conversation
/task-desc
Generate a structured feature description (desc.md) with problem statement, user value proposition, success criteria, scope boundaries, and priority level.
Follows the project’s existing devdocs/ folder conventions for output location. Confirms where to save before writing.
Input: Feature description, /elaborate output, or raw notes
Output: desc.md at confirmed location
/task-plan
Generate a step-by-step implementation plan (step_by_step_plan.md) based on a feature description. Reads all relevant code to understand existing patterns before writing.
If multiple desc.md files exist, lists them and asks which feature to plan for.
Input: desc.md file path, /elaborate output, or direct description
Output: step_by_step_plan.md in the same directory as the desc.md
/critic
Analyze an implementation plan and identify errors, risks, conflicts, and compatibility issues. Produces a critic.md with each risk rated by severity, with ELI5 explanations and mitigation strategies.
If multiple plans exist, lists them and asks which to critique before proceeding.
Input: step_by_step_plan.md file path or direct plan description
Output: critic.md in the same directory as the plan
/critic-d
Dynamic variant of /critic. Instead of using a generic checklist, it first generates a tailored critic prompt based on the specific plan and codebase context, saves it as dynamic_critic_prompt.md for inspection, then executes it after user confirmation.
Two-phase process:
- Generate and save the dynamic prompt — user reviews it
- Execute the prompt and write
critic.md— only after user confirms
Input: step_by_step_plan.md file path or direct plan description
Output: dynamic_critic_prompt.md + critic.md in the same directory as the plan
Foundation Commands
These commands set up a new project’s devdocs from scratch. They form a pipeline — each builds on the output of the previous one.
/devdocs-foundation → /devdocs-foundation-concepts → /devdocs-foundation-simplified-concepts → /devdocs-foundation-identify-modules → /devdocs-foundation-architecture
/devdocs-foundation
Establish the foundational devdocs for a project. Reads all available project context (data dumps, READMEs, conversation history) and creates three foundation documents: project description, philosophy, and known requirements. Works with whatever exists — marks gaps as “unknown” rather than blocking on questions.
Input: None
Output: devdocs/foundations/project_description.md, devdocs/foundations/philosophy.md, devdocs/foundations/known_requirements.md
/devdocs-foundation-concepts
Extract the essential technical concepts from the foundation documents. For each concept, creates a detailed clarification document answering eight structured questions (what it is, how it helps, how it limits, inputs, process, outputs, good outcome, bad outcome).
Input: None (reads foundation docs)
Output: devdocs/concepts/concepts.md + devdocs/concepts/concept_clarifications/01_*.md through NN_*.md
/devdocs-foundation-simplified-concepts
Simplify the full concepts for prototype scope. Reduces features but preserves architecture — the simplified version can expand to the full version without rewrites. Each simplification documents what was cut and why the architecture survives.
Input: None (reads concepts docs)
Output: devdocs/concepts/simplified_concepts.md + devdocs/concepts/simplified_concept_clarifications/01_*.md through NN_*.md
/devdocs-foundation-identify-modules
Identify logical module boundaries from the simplified concepts. Only modularizes at major conceptual boundaries — avoids over-engineering. Documents what was NOT modularized and why.
Input: None (reads simplified concepts)
Output: devdocs/foundations/module_proposal.md
/devdocs-foundation-architecture
Propose the project architecture based on simplified concepts and module proposal. Critically evaluates the module proposal (accepts, merges, or rejects modules). Every design pattern must earn its place by solving a named problem. Documents expansion paths and key trade-offs.
Input: None (reads simplified concepts + module proposal)
Output: devdocs/foundations/architecture.md
Analysis & Sensemaking
/sense-making
Run the Structural Sensemaking Framework against any input. Transforms vague or complex input into stable understanding through five phases: anchor extraction, perspective checking, ambiguity collapse, degrees-of-freedom reduction, and conceptual stabilization. Produces six progressive Sense Versions (SV1–SV6).
Input: Raw text, file path, or file path + additional text Output: Full sensemaking analysis saved as markdown
Thinking Discipline Commands
These commands implement the AlignStack Thinking Disciplines. Each discipline is a domain-agnostic methodology for a specific cognitive operation. They can be used independently or chained via /inquiry.
/innovate
Apply the Structural Innovation Framework to any input. Systematically generates novel ideas using seven mechanisms (4 Generators + 3 Framers) — Lens Shifting, Combination, Inversion, Constraint Manipulation, Absence Recognition, Domain Transfer, and Extrapolation. For each mechanism, produces three variations: one generic, one focused, one controversial. Tests outputs for novelty, scrutiny survival, fertility, and actionability.
Input: Raw text, file path, or file path + additional text Output: Full innovation analysis saved as markdown
/td-critique
Apply the Structural Critique thinking discipline. Constructs evaluation dimensions from the understood problem, builds a multi-dimensional fitness landscape, conducts adversarial testing on each candidate (prosecution + defense + collision), and produces verdicts: SURVIVE, REFINE, or KILL — each with constructive output. The contraction force that turns divergent thinking into convergent results.
Input: Candidates to evaluate + problem context (sensemaking output or equivalent) Output: Fitness landscape with positioned candidates, coverage map, and verdicts saved as markdown
/decompose
Apply the Structural Decomposition thinking discipline. Perceives the internal coupling topology of a complex whole — where things are tightly connected (keep together) vs loosely connected (natural boundary) — and partitions into independently coherent pieces with explicit interfaces and dependency ordering. The scale operator that makes any problem tractable.
Input: Complex problem, task, or system to decompose Output: Coupling map, question tree with pieces, interfaces, and dependency ordering saved as markdown
/explore
Apply the Structural Exploration thinking discipline. Maps unknown territory through iterative scan-signal-probe cycles at managed resolution levels. Two modes: artifact exploration (codebases, literature — find what exists) and possibility exploration (solution spaces, design options — enumerate what could exist). Tracks the frontier between known and unknown with confidence assessment.
Input: Territory to explore (codebase path, problem space, domain) Output: Structural map with confidence levels, frontier, and gaps saved as markdown
/comprehend
Apply the Structural Comprehension thinking discipline. Builds internal working models of observable-but-opaque artifacts through progressive model construction, perturbation testing, and adversarial self-verification. Produces five Comprehension Versions (CV1–CV5) across a depth hierarchy (Descriptive → Structural → Causal → Predictive → Generative). Two primary aspects: mechanistic (“how does it work?”) and intent (“why was it built this way?”). Each CV includes frontier questions — unanswered questions that mark the boundary of current understanding and serve as direction signals for further investigation.
Input: Artifact to comprehend (file path, folder path, raw description) + optional aspect (mechanistic/intent) and depth target Output: Comprehension versions with tested predictions, confidence map, and frontier questions saved as markdown
/navigation
Apply the Structural Navigation thinking discipline. A boundary discipline that maps the full space of possible next directions after a SIC cycle completes. Reads C’s verdicts (survivors, refinements, kill seeds), frontier questions, telemetry, and optionally R’s observations — then produces a navigation map: every possible direction typed from a 15-type taxonomy across 3 categories (content-directed, process-directed, context-directed). Each direction has its own WHY, and 3-6 independently reasoned guidelines (each with its own WHY). Includes confidence levels (■ HIGH / ○ MEDIUM / · LOW) and an excluded section for types considered and rejected. Navigation enumerates WITHOUT selecting — the full space, not a filtered top N.
Navigation replaces wayfinding (superset — 15 types vs 6 moves, full enumeration vs single direction).
Input: Inquiry folder with SIC outputs, raw text describing current state, or file path
Output: Navigation map saved as navigation_N.md (numbered per iteration)
/wayfinding (superseded by /navigation)
Apply the Structural Wayfinding thinking discipline. Produces a single steering move from six options (BROADEN, NARROW, SHIFT, DIAGNOSE, TERMINATE, RECONSIDER). Navigation (/navigation) is the recommended replacement — it produces the full possibility space instead of a single direction.
/inquiry
The loop runner for chaining thinking disciplines. Not a thinking discipline itself — operational plumbing. For NEW inquiries: classifies the problem (CONFIGURE), selects and sequences disciplines into a pipeline, creates an inquiry folder. For RESUME: checks progress and tells you what to run next. After each pipeline iteration: calls wayfinding for a steering checkpoint. Does NOT run disciplines itself — tells you which discipline command to type next.
Input: New question/problem, or existing inquiry folder to resume Output: Pipeline configuration + inquiry folder, or next command to run
/MVL
The minimum viable loop — runs Sensemaking → Innovation → Critique (SIC) on any question. Always the full pipeline, no classification, no variable sequencing. For NEW questions: creates an inquiry folder with _branch.md (question + goal + scope check) and _state.md (progress tracking). For RESUME: reads state, detects which discipline to run next. When the iteration completes: writes finding.md (self-contained argumentative output: Question → Finding → Reasoning → Open Questions) and archives source files to docarchive/. If the question isn’t answered, loops again with refined focus.
Input: New question/description, or existing inquiry folder to resume
Output: Inquiry folder (devdocs/inquiries/<name>/) with _branch.md, _state.md, SIC outputs, and eventually finding.md
/MVL+
The extended cognitive loop — runs Exploration → Sensemaking → Decomposition → Innovation → Critique on any question. Adds two first-phase disciplines (E maps unknown territory, D partitions complexity) that /MVL classic lacks. Strictly sequential in the first phase. Coexists with classic /MVL — _state.md has a flow-type: extended field to distinguish. Use /MVL+ as the default for new inquiries; use /MVL classic for simple well-defined problems when speed matters. When the iteration completes: writes finding.md from six sources (_branch.md + all five discipline outputs) and archives them to docarchive/.
Input: New question/description, or existing extended inquiry folder to resume
Output: Inquiry folder with 5-step progress tracking, all discipline outputs, and finding.md
Archaeology Commands
These commands are for understanding existing codebases. They read code (not documentation) and produce honest assessments of what the project actually is and how it’s built.
/arch-small-summary
Read all code files and produce a non-technical summary of the project — what it does, what state it’s in, who would use it. Based purely on code behavior, not what docs claim.
Input: Optional -n flag (no save)
Output: Saves to devdocs/archaeology/small_summary.md + prints in conversation
/arch-intro
Produce a high-level architecture introduction covering data flow paths, main abstractions, and top-level design patterns. Written as if onboarding a new engineer on their first day.
Input: Optional -n flag (no save)
Output: Saves to devdocs/archaeology/intro2codebase.md + prints in conversation
/arch-traces
Trace every internal interface and submodule-level interaction end-to-end. Creates one file per trace with core sections (entry point, execution path, resource management, error path, performance, observable effects, design rationale) and assessment sections (incomplete, vulnerable, bad design — each with ELI5, impact, and fixes).
Input: None
Output: One file per trace in devdocs/archaeology/traces/
/arch-traces-2
Enhanced version of /arch-traces with structured trace categories. Organizes traces into six categories: lifecycle traces, data transformation traces, integration boundary traces, decision and routing traces, error and recovery traces, and cross-cutting mechanism traces. Each trace includes core sections (entry point, execution path, resource management, error path, performance, observable effects, design rationale) and assessment sections with ELI15 explanations, impact analysis, robust fixes, architectural fixes, and speculative defence for unusual design choices.
Writes a grouped enumeration of all traces before writing individual trace files. Requires codebase understanding — suggests running /arch-small-summary and /arch-intro first if context is missing.
Input: None
Output: One file per trace in devdocs/archaeology/traces/
/arch-top-improvements
Based on existing traces, identify the 5 highest-impact improvements for the codebase. For each, explains why it matters, what it affects, and a plausible reason it hasn’t been done yet (respecting that there may be undocumented decisions behind the current state).
Requires /arch-traces to have been run first.
Input: None
Output: devdocs/archaeology/top_improvements.md
/dead-code-index
Scan the codebase and inventory all unused code candidates — unreferenced files, dead code paths, commented-out blocks, duplicate implementations, abandoned features, orphaned tests and configs. Each candidate gets structured fields (imported by, called by, used in configs, dynamic loading, attached concepts, assumed intent, confidence) plus a ready-to-run grep command for manual verification.
Does not delete anything — inventory only.
Input: None
Output: devdocs/archaeology/dead_code_index.md
/dead-code-concepts
Analyze dead code at a concept level. Groups dead code entries from /dead-code-index into higher-level concepts — technical frameworks, business logic, design patterns, architecture, methodology, conventions — and identifies which ideas the codebase has moved past entirely.
Requires /dead-code-index to have been run first.
Input: None
Output: devdocs/archaeology/dead_concepts_index.md
Navigation
/roadmap
Generate a navigation map from starting state to end state. Creates a roadmap workspace (folder) with persistent context: starting_state.md, end_state.md, and map.md. Starting state is user-controlled — never auto-reads the codebase unless asked. Supports node expansion for progressive refinement. Each node has a five-level status (unknown → concept → designed → planned → done) and a checkbox for progress tracking.
Three-phase workflow:
- Phase 0: Establish context (starting state + end state → save to folder)
- Phase 1: Generate map (nodes + ASCII diagram + summary)
- Phase 2: Expand/update on revisit
Input: Starting state, end state, or existing roadmap folder + node reference
Output: devdocs/roadmaps/<name>/ folder with starting_state.md, end_state.md, map.md
Reporting
/overview-report
Generate a structured report of what happened in the project over a given time period. Combines git history, devdocs artifacts (plans, fixes, traces), and code changes into a readable summary. Each work item gets Why/How/Impact sections. Includes a Direction section connecting individual changes into a trajectory, and a By the Numbers table with concrete metrics.
Input: Time period — 24h, 1d, 7d, 30d (default: 7d)
Output: devdocs/reports/overview_<period>_<date>.md
Alignment
/align
Load all relevant context for a specific task and assess alignment across all six layers. Reads archaeology, task docs, plan, critic, affected modules, and success criteria — then reports gaps and recommends what to do next. After running, the AI has full context loaded and is ready to discuss or implement.
Input: Task path, task name, or description Output: Alignment report printed in conversation (not saved to file)
/align-modes
For a given task, assess what is needed across all seven intent modes (Exploration, Alignment, Innovation, Diagnostic, Maintenance, Recovery, Reflection) and all six alignment layers. Produces a complete strategic picture — not just what to build, but what to explore, what might need innovation, what could break, what to maintain, and what to reflect on. Includes a synthesis with critical items, risk areas, mode sequence recommendation, and recovery plan.
Input: Task path, task name, or description Output: Full multi-modal assessment printed in conversation
Maintenance
/devdocs-archivist
Scan all devdocs, compare each folder and file against the codebase and current context, and determine what should be archived. Staleness is inferred, not declared — the AI checks “does the code reflect what this doc describes?” Archives as a unit (entire folders move together). Cross-reference integrity is preserved — done docs stay if active docs reference them. Each run creates an isolated timestamped folder under devdocs/archive/.
Input: Optional -doc flag (produce report only, don’t move files)
Output: Without -doc: archive plan + confirmation prompt + file moves. With -doc: devdocs/archive_report_<date>.md
Quick Reference
| Command | What it does | Output |
|---|---|---|
/devdocs-foundation | Create foundation docs (description, philosophy, requirements) | devdocs/foundations/ (3 files) |
/devdocs-foundation-concepts | Extract and clarify core concepts | devdocs/concepts/ + clarifications |
/devdocs-foundation-simplified-concepts | Simplify concepts for prototype | devdocs/concepts/simplified_* |
/devdocs-foundation-identify-modules | Identify module boundaries | devdocs/foundations/module_proposal.md |
/devdocs-foundation-architecture | Propose project architecture | devdocs/foundations/architecture.md |
/elaborate | Tidy up messy input | Markdown file(s) + conversation |
/task-desc | Structured feature description | desc.md |
/task-plan | Step-by-step implementation plan | step_by_step_plan.md |
/critic | Risk/error/conflict analysis (generic) | critic.md |
/critic-d | Risk analysis (dynamic, two-phase) | dynamic_critic_prompt.md + critic.md |
/sense-making | Structural sensemaking analysis | Markdown file(s) |
/innovate | Structural innovation (7 mechanisms × 3 variations) | Markdown file(s) |
/td-critique | Structural critique (fitness landscape + adversarial verdicts) | Markdown file(s) |
/decompose | Structural decomposition (coupling map + question tree) | Markdown file(s) |
/explore | Structural exploration (scan-signal-probe + confidence map) | Markdown file(s) |
/comprehend | Structural comprehension (model construction + prediction testing + frontier questions) | Markdown file(s) |
/navigation | Full possibility map (15 types × 3 categories, directions + guidelines) | navigation_N.md per iteration |
/wayfinding | Search steering — superseded by /navigation | Steering directive as markdown |
/inquiry | Loop runner (CONFIGURE + track + resume) | Inquiry folder + next command |
/MVL | Minimum viable loop (S → I → C) | Inquiry folder + finding.md |
/MVL+ | Extended cognitive loop (E → S → D → I → C) | Inquiry folder + finding.md |
/arch-small-summary | Non-technical project summary | devdocs/archaeology/small_summary.md + conversation |
/arch-intro | Architecture introduction | devdocs/archaeology/intro2codebase.md + conversation |
/arch-traces | End-to-end interaction traces | devdocs/archaeology/traces/ |
/arch-traces-2 | Categorized traces (6 categories, enhanced assessments) | devdocs/archaeology/traces/ |
/arch-top-improvements | 5 highest-impact improvements | devdocs/archaeology/top_improvements.md |
/dead-code-index | Inventory unused code candidates | devdocs/archaeology/dead_code_index.md |
/dead-code-concepts | Group dead code into dead concepts | devdocs/archaeology/dead_concepts_index.md |
/roadmap | Navigation map from start to end state | devdocs/roadmaps/<name>/ folder |
/overview-report | Period overview report (why/how/impact) | devdocs/reports/overview_<period>_<date>.md |
/align | Load task context across all 6 layers, report gaps | Alignment report in conversation |
/align-modes | Assess task across 7 modes × 6 layers | Multi-modal assessment in conversation |
/devdocs-archivist | Scan devdocs, detect staleness, archive done work | Archive plan + moves (or -doc report) |
Hooks
| Hook | What it does | Trigger |
|---|---|---|
devdocs_metadata_appender.sh | Auto-injects metadata header (date, branch, commit, author) into devdocs files | PreToolUse on Write |