Markdown spells to stop AI agents from coding themselves into corners

What it does

The repository is a set of Markdown “skills” — not software, just carefully structured prompt documents — that teach compatible AI agents (Claude Code, Codex, Cursor, and others) to run a six-phase spec-driven loop before touching code. It breaks massive requests like “rewrite this in Rust” into project analysis, task decomposition, GitHub Issue/PR tracking, and execution with an adaptive feedback loop. A companion workflow, Deep Discuss, handles structured problem analysis and solution design through disciplined multi-phase thinking.

The interesting bit

The whole system is pure Markdown: no runtime, no dependencies, no SDK. The agent reads the skill file and follows the ritual. The S.U.P.E.R design philosophy — Single Purpose, Unidirectional Flow, Ports over Implementation, Environment-Agnostic, Replaceable Parts — is baked into every phase with compliance scoring, so the agent audits its own architectural health instead of just shipping features.

Key highlights

• Ships two Markdown skills: Spec-Driven Develop for large-scale coding pipelines, and Deep Discuss for structured technical analysis
• Auto-detects GitHub environments and creates Issues, Milestones, worktrees, and linked PRs; falls back to local-only Markdown tracking when the GitHub CLI is unavailable
• Adaptive control loop collects execution telemetry after each task and triggers automatic replanning when drift exceeds 20%, 40%, or 60% thresholds
• S.U.P.E.R compliance checklist runs after every task: modules are scored on single-responsibility, dependency direction, interface contracts, and replaceability
• Platform-agnostic with graceful degradation: works across Claude Code, Codex, Cursor, Windsurf, Cline, Aider, and any Markdown-capable agent

Caveats

• Only Claude Code, Codex, and Cursor have explicit install scripts and testing; other agents require manual copy-paste of SKILL.md and rely on the generic prompt
• Because the project is pure Markdown with no runtime, compliance depends entirely on the agent actually reading and following the skill file

Verdict

Worth a look if you routinely ask AI agents to perform large migrations or refactors and want them to stop, think, and track progress like an engineer rather than an autocomplete engine. Skip it if you are looking for a CLI tool or IDE extension with hard enforcement — this is a discipline system, not a binary.