Frequently Asked Questions

MASTERY.md is a universal, tech-agnostic development process framework distributed as a single Markdown file. It defines a complete software lifecycle with seven stages: Discuss → Design → Plan → Approve → Build → Ship → Reflect.

You copy the file into your project's docs/ folder and follow the process. It works for any project, any language, any stack, and any team size — including solo developers working with AI agents.

Three steps:

1. Create a docs/ folder in your project root
2. Copy mastery.md into docs/mastery.md
3. Start following the process — create your first project-discussion.md

The framework file itself is read-only in your project. All your customizations go into separate files like project-context.md and process-overrides.md.

MASTERY.md works for both new and existing projects. For existing projects, start by creating the core documents:

• project-discussion.md — capture WHY the project exists and key decisions already made
• project-context.md — formalize the project identity, tech stack, and constraints
• project-roadmap.md — list planned features and their current status

Then apply the full lifecycle to new features going forward. You don't need to retroactively document existing work.

Yes. MASTERY.md is open source under the MIT License. You can use it in personal projects, commercial products, open source repos — anything. No attribution required, though it's appreciated.

All of them. MASTERY.md is completely tech-agnostic. It defines a process, not a toolchain. Whether you're building with Go, Python, JavaScript, Rust, C#, or anything else — the lifecycle stages apply universally.

The framework uses only Markdown files, which work with any version control system and any editor.

1. Discuss — Define the problem, explore solutions, make decisions
2. Design — Create architecture and technical design documents
3. Plan — Break work into specific, actionable tasks
4. Approve — Human reviews and approves design + plan before building
5. Build — Implement the code, following the task list
6. Ship — Deploy, merge, and release
7. Reflect — Review what went well, what didn't, and what to improve

Generally, no — each stage builds on the previous one. Skipping stages is how projects lose structure and accumulate tech debt.

However, for lightweight features (small bug fixes, copy changes, config updates), you can use an abbreviated flow documented in the framework. The key is that some level of discussion and planning always happens, even if it's brief.

Discuss is about the problem — WHY are we building this? What are the options? What decisions need to be made? It captures the reasoning and constraints.

Design is about the solution — HOW will we build it? What's the architecture? What components, APIs, data models are needed? It turns decisions into a technical blueprint.

The Approve stage is a deliberate checkpoint where a human reviews the design and plan before any code is written. This prevents wasted effort building the wrong thing.

It's especially important when working with AI agents, who can write code very fast but may misunderstand intent. The Approve gate ensures alignment before the expensive Build phase begins.

After shipping, you review the feature lifecycle:

• What went well?
• What was harder than expected?
• Were there any process improvements to make?
• Did the original discussion and design hold up during implementation?

Reflections are recorded in the feature's changelog and feed into future improvements. They're short — usually a few bullet points.

The framework includes a dedicated AI Agent Protocol section that defines how AI coding assistants should interact with the process. When an AI agent starts working on a project, it reads mastery.md first to understand:

• The context loading order (which docs to read and in what sequence)
• Autonomy boundaries (what it can do alone vs. what needs human approval)
• Session handoff protocol (how to resume interrupted work)
• Communication style rules

AI agents can autonomously:

• Read all project documentation
• Write code within active tasks
• Check off completed tasks
• Log changelog entries and session notes
• Create commits on feature branches
• Push to feature branches

AI agents cannot autonomously: merge to main, modify approved architecture, change project-context.md, reorder the roadmap, or add dependencies. These require human approval.

Yes. The framework is designed for any AI coding assistant that can read Markdown files. It works with ChatGPT, Claude, GitHub Copilot, Cody, Cursor, Windsurf, and any future AI tool that follows instructions in documentation.

The key is that the AI reads mastery.md at the start of each session. Most modern AI coding tools do this automatically when pointed at a project's docs.

When an AI agent's session ends (context window fills, timeout, or interruption), it should:

1. Document where it stopped in the feature's changelog
2. Note any in-progress work or blockers
3. Commit and push current state to the feature branch

When a new session starts, the agent reads the docs in order and picks up exactly where the previous session left off. This enables seamless multi-session development.

At minimum, every project using MASTERY.md needs:

• docs/mastery.md — The framework file (read-only copy)
• docs/project-discussion.md — WHY the project exists, key decisions
• docs/project-context.md — Formalized project identity (name, tech stack, conventions)
• docs/project-roadmap.md — Feature ordering and progress tracking

Each feature then gets its own folder under docs/features/ with discussion, architecture, tasks, and changelog files.

Each feature folder (docs/features/XX-feature-name/) contains:

• discussion.md — Problem statement, proposed solutions, decisions
• architecture.md — Technical design, data models, component structure
• tasks.md — Ordered checklist of implementation tasks
• testplan.md — Testing strategy and verification steps
• changelog.md — Session notes and feature history

Not every feature needs all files. Lightweight features may skip architecture or testplan.

Markdown files in a docs/ folder are:

• Version controlled — they travel with the code in git
• Portable — no vendor lock-in to any platform
• AI-readable — AI agents can read them instantly without API access
• Branch-aware — feature docs live on feature branches alongside the code
• Offline — no internet required

External tools (wikis, Jira, Notion) create information silos that AI agents can't access and that don't branch with the code.

Feature branches follow the pattern: feature/XX-feature-name

Where XX is the feature number from the roadmap (zero-padded) and feature-name is a short kebab-case description. Examples:

• feature/01-project-setup
• feature/05-user-auth
• feature/12-responsive-polish

Commits follow the conventional format: type(scope): short description

Types include: feat, fix, docs, style, refactor, test, chore, perf, hotfix

The scope is the feature name or module. Examples:

• feat(auth): add email verification flow
• fix(feedback): validate category before database insert
• docs(mastery): update AI agent protocol section

Feature branches are kept forever as historical reference. They contain the complete evolution of a feature — every commit, every doc change, every iteration. This provides:

• Full audit trail for decisions and implementation
• Easy reference when similar features are built later
• Context for understanding why code was written a certain way

The storage cost is negligible compared to the historical value.

Absolutely — it was designed with solo developers in mind, especially those working with AI agents. The framework provides structure without bureaucracy. Solo developers benefit from:

• Documenting decisions before you forget why you made them
• Having a clear task list to follow (prevents scope creep)
• Giving AI agents the context they need to help effectively
• Building a project history that's invaluable when revisiting code months later

For teams, MASTERY.md scales naturally because everything is in git:

• Discussion and design docs can be reviewed in pull requests
• The Approve stage maps to team review/sign-off
• Multiple developers can work on separate feature branches in parallel
• The roadmap provides shared visibility into what's being built

The framework doesn't prescribe team roles — it defines a process that any team structure can follow.

Yes. Each feature lives on its own branch with its own documentation folder. Multiple features can progress through different lifecycle stages simultaneously. The roadmap tracks which features are active, planned, or completed.

The only constraint is that features should be merged to main one at a time to avoid complex merge conflicts.

Create a docs/references/process-overrides.md file. This is where you document any deviations from the standard process:

• Stages you always abbreviate (e.g., skip testplan for frontend-only changes)
• Additional review steps your team requires
• Modified commit conventions
• Custom branch naming patterns

The framework file (docs/mastery.md) stays read-only so you can upgrade to new versions without conflicts.

It's an optional file at docs/references/process-overrides.md that documents your project-specific process customizations. Think of it as your project's "local config" that overrides the framework's defaults.

AI agents read this file during their context loading sequence and apply your overrides automatically.

Yes. MASTERY.md defines a feature lifecycle, not a project management methodology. It complements Agile, Scrum, Kanban, or any other approach:

• Sprint items map to features on the roadmap
• Each sprint item follows the 7-stage lifecycle
• Retrospectives map to the Reflect stage

The framework adds structure to how individual features are built, regardless of how work is organized at the project level.

Hotfixes use an abbreviated lifecycle. Create a hotfix/description branch from main, fix the issue, document briefly, and merge. The key stages are compressed:

• Discuss — Brief problem description (can be one paragraph)
• Build — Fix the bug
• Ship — Deploy immediately

Full documentation can be added retroactively if needed.

Small changes (copy updates, config changes, dependency bumps) don't need the full 7-stage treatment. The framework supports lightweight features with:

• A single discussion entry (a few sentences explaining the change)
• A minimal task list
• No separate architecture or testplan docs

Document the criteria for what counts as "lightweight" in your process-overrides.md.

Yes. Start by creating the core project documents (discussion, context, roadmap) to capture the current state. Then apply the full lifecycle to all new features going forward.

You don't need to retroactively document existing features — but you might want to create brief entries for major past decisions so the history is accessible.

MASTERY.md is currently at v3.3.0. Check the changelog for version history and release notes.

You can:

• Open an issue on GitHub
• Send us feedback through the website
• Read through this FAQ and the framework documentation

Most development frameworks are either too heavy (enterprise methodologies with dozens of ceremonies) or too light (just "use git" with no process). MASTERY.md sits in the sweet spot:

• One file — no complex tooling setup
• Seven clear stages — not a dozen ceremonies
• AI-native — built for human + AI collaboration
• Tech-agnostic — works everywhere, no vendor lock-in
• Scales down — a solo developer gets the same structure as a team

Yes — MASTERY.md develops itself using its own framework. The GitHub repository contains a docs/ folder with all the lifecycle documents for every feature of the framework. This "dogfooding" ensures the process is practical and battle-tested.

Yes! MASTERY.md is open source and welcomes contributions. The best ways to contribute:

• Submit feedback about your experience using the framework
• Open issues or pull requests on GitHub
• Share the framework with other developers