SlashStack

A repo-local agent operating layer for serious builders.

SlashStack installs durable context and disciplined workflows into your project so coding agents plan better, verify harder, remember what matters, and improve from failures. No hosted service, no accounts, no lock-in — just transparent files you can read, edit, and version control.

What it is

Most agent sessions start from zero: no project memory, no conventions, no review checklist, no accumulated lessons. SlashStack fixes this by installing a local operating layer into the repository itself:

• Kernel (AGENTS.md) — The root contract that tells compatible agents how to work in this repo.
• Skills — Slash-style workflows agents invoke at the right moment (planning, preflight, review, memory, verification).
• Memory — Durable project facts and subsystem references that survive across sessions.
• Self-improvement patterns — A conservative learning loop that captures reusable lessons without silently rewriting rules.

Everything is plain text, stored locally, tracked by a manifest so SlashStack knows what it owns.

Software Factory (first vertical)

SlashStack can prepare a small, repo-local delivery loop without replacing your coding agent:

# Inspect the repository and create a factory profile
npx slashstack factory init

# Turn an intention into a bounded order
npx slashstack factory order create \
  --title "Add the export filter" \
  --acceptance "The export contains only the selected records." \
  --bind-test

# Run the detected project test command and write a local receipt
npx slashstack factory verify order-<id>

# Vertical 2 — let the configured agent implement the order in an
# isolated git worktree, then verify the result automatically
# (requires agent.command in .agents/factory/config.json)
npx slashstack factory run order-<id>

factory run never touches your main checkout: the agent works in .agents/factory/runs/<order-id>, and the receipt records the agent's exit code, the verification result, and the worktree path. Merge and deploy stay human decisions. The run blocks (never fakes success) when no agent command is configured, when another run is active, or when the frozen verifier no longer matches.

The profile lives in .agents/factory/config.json. Orders and receipts are stored under .agents/factory/. factory init only detects the project and creates those local files; it does not edit application code. factory verify runs the frozen test command captured when the order was created. A passing command is not enough: passed requires --bind-test, which explicitly treats that frozen command as the mechanical acceptance check. Without it, verification is blocked with acceptance_not_evaluated.

Verification is also blocked when the command or package.json test script changed after the order was created, when the worktree changes during the check, or when no test command exists. The receipt records the pre-check Git identity. Command output is redacted before it is stored; do not treat the receipt as a safe place for secrets.

This first vertical does not provide a scheduler, autonomous merge, deployment, sandbox, or unlimited model execution. The order is a contract for a verifiable handoff, not proof that the product is correct beyond the checks it names.

Quickstart

SlashStack is published on npm as slashstack — website: slashstack.dev.

# Install the agent layer into the current project
npx slashstack install

# Check what is installed
npx slashstack status

# Refresh skills and kernel to the latest bundled version
npx slashstack update

# Remove SlashStack-managed files
npx slashstack uninstall

# Verify a license key
npx slashstack verify-key <key> --email <email>

Install targets

By default, SlashStack installs skills under .agents/skills/. You can also target Claude-compatible projects:

npx slashstack install --target agents   # portable default
npx slashstack install --target claude   # skills go under .claude/skills/

Coexisting with an existing AGENTS.md

SlashStack never takes over a project's own instruction file. The kernel is embedded as a managed block delimited by markers:

<!-- slashstack:kernel:start -->
...SlashStack Agent Kernel...
<!-- slashstack:kernel:end -->

• AGENTS.md missing → SlashStack creates it containing only the marked block.
• AGENTS.md already exists → the marked block is appended; your existing content is never modified.
• update refreshes only the content between the markers; anything you write outside them survives.
• uninstall removes only the block; the file is deleted only if nothing else remains.

If you prefer the kernel outside AGENTS.md entirely, use --kernel=separate: the full kernel goes to .agents/SLASHSTACK.md and your instruction file gets a one-line marked pointer (for --target claude, a @.agents/SLASHSTACK.md import line in CLAUDE.md).

npx slashstack install --kernel separate

Additional options

# Preserve memory and references on uninstall
npx slashstack uninstall --keep-memory

# Run against a different project root
npx slashstack install --project-root ./my-project

Git worktrees

SlashStack Pro supports projects checked out with git worktree. In a worktree, .git is a file that points to Git's administrative directory rather than a .git/ folder. SlashStack resolves the hook path through Git itself, so Pro installation, update, and uninstall do not modify or replace the worktree's .git file.

If you want to confirm the hook location Git will use:

git rev-parse --git-path hooks

What gets installed

Running npx slashstack install creates the following files and directories:

| Path | Purpose | |------|---------| | AGENTS.md | Root operating contract for agents — SlashStack owns only the marked kernel block; everything else is yours | | .agents/SLASHSTACK.md | Full kernel in --kernel=separate mode, pointed to from your instruction file | | .agents/skills/<skill>/SKILL.md | Twenty slash-style workflow skills | | .agents/guards/<guard>.md | Six always-on guards for dangerous boundaries | | .agents/memory/project.md | Stable project facts for future sessions | | .agents/references/README.md | Template for durable subsystem maps | | .agents/memory/patterns.json | Store for reusable self-improvement patterns | | .agents/memory/goal-registry.json | Durable store for active and completed goals | | .agents/memory/checkpoints.json | Durable store for clean Git checkpoints (Pro) | | .agents/references/goal-template.md | Template for creating new goals with scope, acceptance, and verification | | .agents/skills/.slashstack-install.json | Manifest tracking managed files |

Available workflows

SlashStack installs twenty skills that shape agent behavior:

| Skill | When to use | |-------|-------------| | vibe | Turn rough intent into a focused, scoped build direction. Defines scope (in-scope and out-of-scope) and identifies the single next step. | | preflight | Inspect repo state, conventions, and constraints before editing code. Summarizes repo state, verification commands, and flags risks with severity. | | audit | Review changes for bugs, regressions, missing tests, and release risk. Produces evidence-backed approval or rejection with specific issues and severity levels. | | remember | Save durable subsystem knowledge after a useful session. Stores only durable facts, rejecting transient state, secrets, and one-off TODOs. | | recall | Load saved subsystem context before working in that area. Validates references against the current codebase and summarizes subsystem purpose, entry points, conventions, and risks. | | improve | Capture reusable workflow patterns that should shape future agent work. Proposes skill updates without overwriting existing learning. | | ship | Run final verification and produce evidence-backed handoff. Checks for blockers and produces a go/no-go decision with an evidence summary. | | execute | Turn a multi-step task into a scoped goal with acceptance criteria, verification commands, and commit/push expectations. Tracks state in the goal registry and prevents parallel goals from overlapping file scopes. | | explain | Translate technical agent output into beginner-friendly language while preserving exact file paths, commands, and errors. | | next | Suggest 2-3 safe next prompts when the user does not know what to ask next, without editing until the user chooses. | | security | Run a beginner-friendly pre-deploy safety review for secrets, auth, public routes, and risky exposure. | | factory | Turn an intention into a bounded factory order with frozen verification, then verify it through slashstack factory and deliver a receipt tied to the exact repository state. Links to the goal registry as the delivery contract for a goal. | | spawn | Decompose a large task into 2-4 independent sub-goals with disjoint write scopes, dispatch them via the host tool's native parallelism, then gather and verify results in the goal registry. | | cost | Scan the diff and dependencies for paid-service SDKs (stripe, openai, twilio, AWS, etc.) and produce a plain-language bill-risk table with estimated cost categories. | | new | Create a custom user-owned slash command as a SKILL.md in the skills directory. User skills are never added to the manifest, so they survive update and uninstall. | | forget | List entries from project.md and patterns.json, confirm which to remove, remove them, and validate store integrity. Completes the remember/recall/forget triad. | | sync | Compare dependency versions against known latest releases, record deltas in project memory under a "Dependencies" section, and flag security advisories. | | mobile | Check mobile/responsive readiness: key viewport breakpoints (320, 375, 768, 1024), touch-target sizes (≥44px), responsive image srcset/loading, and fixed-width elements. Outputs a pass/fail checklist. | | health | Pull recent production errors through the cloud CLI the repo already has authenticated (vercel, supabase, fly, etc.) and summarize them by frequency and severity, flagging regressions from previous checks. | | senior | Adopt a lazy-senior posture: confirm the smallest surface, prefer stdlib/native/understood deps over new ones, verify with the smallest runnable check, then stop. (Pro) |

Always-On Guards

SlashStack installs six guards into .agents/guards/ (always .agents/, even with the Claude target — guards are universal). The kernel instructs agents to read and apply the matching guard before any git commit, git push, package install, or edit to a hands-off file, and before ending a session:

| Guard | What it does | |-------|--------------| | commit-guard | Before any git commit, scans the staged diff for secret patterns (sk-, AKIA, -----BEGIN, .env paths, conflict markers) and refuses the commit if found. | | push-guard | Before any git push, scans the outgoing commit history for secrets that escaped commit-guard. The second gate. | | install-guard | Before installing a new package, checks for typosquatting (close edit distance to popular names) and flags suspicious packages. | | fragile-guard | Before editing files listed under "## Hands-Off Files" in project memory, warns and asks for confirmation. | | env-guard | Compares .env.local keys against .env.example and flags missing or extra keys (drift), never printing values. | | memory-nudge | Before ending a session, prompts to run the remember workflow to capture durable knowledge. |

Guards are tracked in the manifest under managedGuards; uninstall removes only managed guard files and keeps the directory if you added your own.

Goal Registry

.agents/memory/goal-registry.json tracks active and completed goals. Each goal carries explicit scope (file path globs), acceptance criteria, verification commands, and completion state. A goal is only marked complete after its verification commands pass and any commit/push expectations are satisfied. Goals may run in parallel only when their write scopes do not overlap.

Goal registry contract v1

The registry must be valid JSON with this top-level shape:

{
  "version": 1,
  "goals": []
}

Each goal entry includes these fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Unique goal identifier | | title | string | Human-readable goal title | | scope | string[] | File path globs the goal may read or write | | acceptance | string | What "done" looks like | | verification | string[] | Commands that must pass before completion | | commitExpectation | boolean | Whether changes must be committed | | pushExpectation | boolean | Whether the branch must be pushed | | status | string | pending, active, completed, or abandoned | | createdAt | ISO string | When the goal was created | | updatedAt | ISO string | When the goal was last updated | | archived | boolean | Whether the goal is archived (stale completed goals) |

Pattern Store

.agents/memory/patterns.json is the durable store for the improve workflow. It captures reusable repository-specific tactics, mistakes to avoid, verification habits, and conventions that should shape future agent sessions.

Contract v1

The store must be valid JSON with this top-level shape:

{
  "version": 1,
  "patterns": []
}

Each pattern is an object with these required fields:

| Field | Type | Description | |-------|------|-------------| | name | string | Human-readable pattern name | | trigger | string | When to apply this pattern | | action | string | What to do when triggered | | evidence | string | Why this pattern matters | | confidence | number (0–1) | Certainty that the pattern is valid | | sources | string[] | Where the pattern was observed | | createdAt | ISO string | When the pattern was first captured | | id | string (optional) | Deduplication key; defaults to kebab-case name |

Deduplication and merging

Patterns are deduplicated by id. When a pattern with the same id is added again:

• The higher confidence value is kept.
• sources arrays are combined and deduplicated.
• The older createdAt timestamp is preserved.

Safety guarantees

• Strict validation. Install, update, and the improve skill validate the entire file against the v1 contract. Any malformed JSON, missing required field, or out-of-range value causes a loud failure.
• Fail loud. Invalid stores throw errors rather than being silently repaired or overwritten. This prevents agents from accidentally destroying learned patterns.
• Preserved on uninstall. uninstall never removes .agents/memory/patterns.json, even without --keep-memory, because learned patterns are durable user data.

Tiers

SlashStack ships in two tiers:

• Free — 12 skills (planning, preflight, audit, remember, recall, improve, ship, execute, explain, next, security, factory) and the six always-on guards.
• Pro — All 20 skills plus Senior Mode planning, slashstack protect (installs owned pre-commit and pre-push hooks that scan staged content and outgoing history for secrets), and slashstack checkpoint create | list | recover <id> (clean Git snapshots you can roll back to on a new branch).

Senior Mode is invoked through the senior skill or inherited automatically when the agent adopts the lazy-senior posture; it shapes preflight, implementation, audit, and ship into the smallest surface that works.

Safety model

SlashStack is designed to be safe to try and safe to remove:

• No overwrite of user files. install refuses to overwrite an existing AGENTS.md or skill directory unless SlashStack previously created it.
• Memory is preserved. Existing .agents/memory/project.md and .agents/references/README.md are never overwritten.
• Patterns survive reinstall. .agents/memory/patterns.json is preserved across uninstall and install cycles because learned patterns are durable user data.
• Goal registry survives reinstall. .agents/memory/goal-registry.json is preserved on uninstall because goal history is durable user data.
• Manifest-based cleanup. uninstall removes only files listed in the manifest. Use --keep-memory to preserve memory and references as well.
• Transparent. Everything is a plain text file you can inspect in version control.

Requirements

• Node.js >= 20
• Zero dependencies

Roadmap

SlashStack is under active development. The current plan:

1. Self-improvement workflow (complete) — Conservative learning loop with episodic memory, pattern extraction, and human-reviewed skill update proposals.
2. Production-useful skills (complete) — Twelve slash-style workflow skills with practical senior-engineer guidance and beginner support.
3. Package quality (complete) — Smoke tests, npm-ready packaging, MIT license, and a sub-five-minute README quickstart.
4. Goal-driven execution (complete) — Harness support for scoped milestones with acceptance criteria, verification, goal registry, goal template, and twelve installed workflows.
5. Commercial validation (active) — Use tester evidence to validate Founder License demand manually, then decide whether premium workflows, paid distribution, or SaaS team tooling are justified.

Local development

# Run the test suite
npm test

# Run the CLI locally
node src/index.js install --target agents
node src/index.js status

License

MIT