mstack is a Markdown-first Cursor Agent workflow pack: phase-separated work, token discipline, permission gates, and specialist rules you can copy into any codebase. It ships as .cursor/rules/*.mdc, root AGENTS.md, and templates/.

This repository is also a reference implementation: it includes docs/ for agent-oriented memory and an optional Ideas HTTP API (src/, tests/) that exercises structured API patterns.

• npm package.json name is mstack (workspace / repo identity). GET /v1/meta returns product: mstack and service: mstack-ideas-api for the HTTP demo. See docs/ARCHITECTURE.md, docs/DEMO_WALKTHROUGH.md.

flowchart LR
  subgraph layerA [Layer_A_mstack_core]
    rules[rules_templates_docs]
  end
  subgraph consumer [Consumer_repo]
    copied[copied_via_sync]
  end
  subgraph layerB [Layer_B_reference_only]
    api[src_tests_Ideas_API]
  end
  layerA -->|sync-mstack.sh| copied
  layerB -->|stays_in_this_repo| maintainer[maintainers_and_demo_users]

Inspired by the “virtual team” workflow idea popularized by GStack (Claude Code). mstack is independent content for Cursor; it is not a fork of GStack.

Reality check: mstack is team glue and guardrails, not automatic model intelligence. See docs/EFFECTIVENESS.md for when it tends to help, when it does not, and known weak spots. Token habits (honest): docs/TOKEN_LEVERS.md.

Why bother? One-page pitch + honest comparison: docs/WHY_MSTACK.md.

Where to start (by role): docs/DOCS_MAP.md — first links for mobile, first-time install, daily dev, champions, agents.

If this helps your team, star the repo and open a PR — see CONTRIBUTING.md and docs/SHOWCASE.md. Spread the word: docs/SHARE_AND_COMPARE.md, /mstack-pitch-short, docs/BADGE.md. Security: SECURITY.md.

Fastest install (another repo): docs/STARTER_KIT.md — sync, doctor, first Agent messages.

flowchart TB
  subgraph adopt [Adopt]
    P[Pack choice docs/PACKS.md]
    S[sync-mstack.sh + scripts/packs/*.txt]
  end
  subgraph cursor [Cursor]
    R[.cursor/rules mstack-*.mdc]
    A[AGENTS.md]
    K[.cursor/skills optional]
  end
  subgraph artifacts [Artifacts]
    T[templates/*.md]
    M[docs/PROJECT_MEMORY.md]
  end
  subgraph verify [Verify]
    D[mstack-doctor.sh]
    V[verify-mstack-sync.sh --strict]
  end
  P --> S
  S --> R
  S --> T
  S --> K
  R --> A
  R --> T
  R --> M
  D --> R
  V --> R

Human-readable detail: docs/workflow.md. Preset rule bundles: docs/PACKS.md.

Rules use YAML frontmatter (description, globs, alwaysApply). See Cursor Rules. You can @mention a rule in chat (e.g. @mstack-debug, @mstack-model-strategy).

Overlapping specialists: Some pairs cover similar areas with different scope—for example mstack-docs-devx vs mstack-docs-ship, mstack-data-modeling vs mstack-data-migrations, mstack-ci-quality vs mstack-ci. Keep both or delete one set when vendoring into a smaller project.

Recommended minimum when copying elsewhere: mstack-core-workflow, mstack-token-discipline, mstack-permissions.

mstack targets Cursor Agent (chat + project rules). It pairs with normal IDE work—editor, search, terminal, debugger, Tab—for fast local edits; use Agent + phases when scope is wide or you want rule-consistent behavior. See docs/CURSOR_INTEGRATION.md.

• Modes: Use the Agent mode picker or Shift+Tab to switch Agent, Plan, and Debug modes (Plan, Debug).
• Plan Mode: Best for unclear requirements or many files; refine the plan before Build.
• Debug Mode: Best for runtime evidence; mstack still requires your OK before extra logging or reproduce-for-logs steps (mstack-debug.mdc).
• Model picker / Auto: mstack may suggest a faster vs more capable tier in chat; only you can change the model—project rules cannot.
• Web: No external fetches for design research unless you explicitly allow it for that task.

Canvas lets the agent open interactive dashboards (tables, diagrams, todos) as durable artifacts in the Agents Window. This repo includes project skills: mstack-flight-deck — type /mstack-flight-deck for a Canvas overview (phases, docs, Ideas API; node scripts/ideas-snapshot.mjs). mstack-doctor — type /mstack-doctor to run local install checks (scripts/mstack-doctor.sh). mstack-pack-picker — type /mstack-pack-picker to choose MSTACK_PACK. mstack-first-sync — type /mstack-first-sync for copy-paste sync + merge hints when adopting in a new repo. mstack-upgrade-vendor — type /mstack-upgrade-vendor after updating vendor/mstack (submodule pull → re-sync → doctor). mstack-context-budget — type /mstack-context-budget for a pasteable file cap + narrow @ block (long threads). mstack-ship-check — type /mstack-ship-check for a pre-merge / pre-PR checklist to paste into GitHub. mstack-agent-habits — type /mstack-agent-habits for a pasteable Agent kickoff (progress notes, bounded reads, mstack hooks); see docs/CURSOR_BASE_BEHAVIOR.md. mstack-pitch-short — type /mstack-pitch-short for README / Slack blurbs; see docs/SHARE_AND_COMPARE.md. Full index: docs/SKILLS.md. Paths: .cursor/skills/mstack-flight-deck/SKILL.md, .cursor/skills/mstack-doctor/SKILL.md, .cursor/skills/mstack-pack-picker/SKILL.md, .cursor/skills/mstack-first-sync/SKILL.md, .cursor/skills/mstack-upgrade-vendor/SKILL.md, .cursor/skills/mstack-context-budget/SKILL.md, .cursor/skills/mstack-ship-check/SKILL.md, .cursor/skills/mstack-agent-habits/SKILL.md, .cursor/skills/mstack-pitch-short/SKILL.md.

Prefer the single-page guide: docs/STARTER_KIT.md. Or follow the steps below.

1. Copy AGENTS.md, .cursor/rules/mstack-*.mdc, and optionally templates/ into your project.
2. Merge AGENTS.md with your existing file if needed.
3. In Cursor, rules load from .cursor/rules/ and AGENTS.md per Cursor Rules.
4. Say: Use mstack phases or step through Think → Plan → Build.

# In your app repo root
cp /path/to/mstack/AGENTS.md .
mkdir -p .cursor/rules templates
cp /path/to/mstack/.cursor/rules/mstack-*.mdc .cursor/rules/
cp -r /path/to/mstack/templates/* templates/

git submodule add <this-repo-url> vendor/mstack
mkdir -p .cursor/rules
ln -sf ../../vendor/mstack/.cursor/rules/mstack-*.mdc .cursor/rules/
cp vendor/mstack/AGENTS.md ./AGENTS.md.mstack-snippet   # merge manually into your AGENTS.md

Re-init after clone: git submodule update --init --recursive.

From your app repo with mstack at vendor/mstack:

chmod +x vendor/mstack/scripts/sync-mstack.sh
# Curated pack + project memory bootstrap (recommended for most apps)
MSTACK_ROOT=vendor/mstack MSTACK_PACK=standard INIT_PROJECT_MEMORY=1 vendor/mstack/scripts/sync-mstack.sh

Defaults: MSTACK_PACK=all copies every mstack-*.mdc (same as before). Set MSTACK_PACK to minimal, lite, solo, standard, or full to copy only the rules listed in vendor/mstack/scripts/packs/<pack>.txt. SYNC_TEMPLATES=0 skips templates/*.md. INIT_PROJECT_MEMORY=1 creates docs/PROJECT_MEMORY.md from the template if missing.

Doctor (required trio + optional strict pack check): bash vendor/mstack/scripts/mstack-doctor.sh . — with MSTACK_ROOT, MSTACK_PACK, and MSTACK_VERIFY_STRICT=1 also runs verify. In this repo: npm run mstack:doctor.

Verify .cursor/rules matches the pack (e.g. in CI): MSTACK_ROOT=vendor/mstack vendor/mstack/scripts/verify-mstack-sync.sh --strict standard. Example workflow: .github/workflows/mstack-pack-verify.yml.example. See docs/POWER_USER.md.

Also copies templates/*.md (unless skipped) and .cursor/skills/* when present. With SYNC_AGENTS_SNIPPET=1, also writes AGENTS.md.mstack-snippet for manual merge.

Remove any specialist you do not need. For curated lists (minimal, lite, solo, standard, full), see docs/PACKS.md and use MSTACK_PACK. At minimum, keep mstack-core-workflow.mdc, mstack-token-discipline.mdc, and mstack-permissions.mdc.

When you change the Ideas API, routes, env vars, or layout, update:

• docs/AGENT_MEMORY.md — orientation and glossary
• docs/ARCHITECTURE.md — system map
• docs/DECISIONS.md — decision log
• docs/PROJECT_MEMORY.md — design language, product terminology, standing user preferences (when explicitly agreed)

Rule mstack-repo-memory.mdc reminds agents to use these when editing docs/, src/, or tests/ here. Rule mstack-project-memory.mdc applies when editing project memory, design briefs, or theme/tokens paths.

AGENTS.md
CONTRIBUTING.md
CODE_OF_CONDUCT.md
CHANGELOG.md
LICENSE
README.md
.github/
  workflows/mstack-pack-verify.yml.example
  ISSUE_TEMPLATE/
  PULL_REQUEST_TEMPLATE.md
.cursor/rules/mstack-*.mdc
.cursor/skills/mstack-flight-deck/
.cursor/skills/mstack-doctor/
.cursor/skills/mstack-pack-picker/
.cursor/skills/mstack-lean-handoff/
.cursor/skills/mstack-first-sync/
.cursor/skills/mstack-upgrade-vendor/
.cursor/skills/mstack-context-budget/
.cursor/skills/mstack-ship-check/
.cursor/skills/mstack-agent-habits/
.cursor/skills/mstack-pitch-short/
.cursor/skills/mstack-scorecard/
.cursor/skills/mstack-demo-consumer/
SECURITY.md
docs/
  workflow.md
  DOCS_MAP.md
  WHY_MSTACK.md
  CONTEXT_BUDGET.md
  STARTER_KIT.md
  VENDOR_UPGRADE.md
  MONOREPO.md
  RECIPES.md
  TEAM_ROLLOUT.md
  RULES_SOURCE.md
  SKILLS.md
  GLOSSARY.md
  ANTI_PATTERNS.md
  CURSOR_MCP.md
  ONBOARDING.md
  PLAYBOOK.md
  GSTACK_INSPIRATION.md
  TROUBLESHOOTING.md
  CURSOR_LIMITS.md
  CURSOR_BASE_BEHAVIOR.md
  CURSOR_INTEGRATION.md
  POWER_USER.md
  ADOPTION_AUDIT.md
  ADOPTION_SCORECARD.md
  PLAYBOOK_FIRST_MESSAGES.md
  TOKEN_LEVERS.md
  EFFECTIVENESS.md
  SPECIALIST_MAP.md
  SHOWCASE.md
  SHARE_AND_COMPARE.md
  BADGE.md
  FAQ.md
  PACKS.md
  AGENT_MEMORY.md
  ARCHITECTURE.md
  DECISIONS.md
  PROJECT_MEMORY.md
  DEMO_WALKTHROUGH.md
  SRC_INTERNAL.md
  sample-workflow/
scripts/sync-mstack.sh
scripts/verify-mstack-sync.sh
scripts/mstack-doctor.sh
scripts/mstack-scorecard.sh
scripts/mstack-demo-consumer.sh
scripts/mstack-ci-local.sh
scripts/verify-packs-internal.sh
scripts/packs/*.txt
scripts/ideas-snapshot.mjs
templates/*.md
package.json          # npm workspace name mstack; scripts run reference API
src/                  # mstack-ideas-api reference service
tests/                # Vitest for reference API
docs/sample-workflow/ # Example plan/debug/ADR/runbook snippets

A small Node/TypeScript HTTP service: validation, session preferences, idempotency (replay + 409 on body mismatch), rate limits. Default store is in-memory (restart clears). Optional file-backed persistence: set IDEAS_STORE_PATH to a JSON file path (demo-only; not for high concurrency). Internal map: docs/SRC_INTERNAL.md.

npm install
npm run dev

Default port 3000 (PORT). Optional: RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS.

Responses include X-Request-ID and JSON requestId.

npm test
npm run lint
npm run build && npm start

Longer guide: docs/TROUBLESHOOTING.md.

MIT — see LICENSE.

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md
• docs/FAQ.md
• docs/SHOWCASE.md