Brownfield Project¶

Adding learnship to an existing codebase takes one extra step: /map-codebase before /new-project. This gives the agent a grounded understanding of what already exists so it doesn't contradict the architecture.

The pattern¶

/map-codebase             # understand the existing code
/new-project              # questions focus on what you're ADDING
# normal phase loop from here

Step 1: Map the codebase¶

/map-codebase

The agent analyzes your existing codebase and produces .planning/codebase/:

.planning/codebase/
├── STACK.md         # tech stack, frameworks, key dependencies
├── ARCHITECTURE.md  # structural patterns, module relationships
├── CONVENTIONS.md   # naming, file organization, coding style in use
└── CONCERNS.md      # identified tech debt, risks, areas to avoid

Example CONCERNS.md output:

## CONCERNS

1. Auth module: mixed synchronous and async patterns, no consistent error handling
2. Database layer: raw SQL mixed with Knex queries in the same files
3. No test coverage for the payment module (0%)
4. `utils/helpers.js` is a 1200-line catch-all: high coupling risk

This file is read by every subsequent planner: it shapes which areas get touched and which are avoided.

Step 2: Initialize the project¶

/new-project

With CODEBASE/ artifacts present, the questions shift:

What are you ADDING to this codebase?
→ A notification system: email + in-app: triggered by task events

What should this milestone NOT change?
→ Auth system (active users), payment module (undergoing audit), public API shape

What existing patterns should the new code follow?
→ Async/await throughout, Knex for DB queries, Jest for testing

The roadmap is scoped to the new feature only: it won't touch the auth system or payment module because those are explicitly off-limits.

Step 3: Normal phase loop¶

From here the workflow is identical to greenfield:

/discuss-phase 1        # align on notification architecture decisions
/plan-phase 1           # research + create plans that fit the existing stack
/execute-phase 1        # build following existing conventions
/verify-work 1          # UAT against acceptance criteria

The planner reads CONVENTIONS.md and follows them. It reads CONCERNS.md and avoids the flagged areas. Nothing is guessed.

Discovery when entering unfamiliar code¶

If a phase touches an area you haven't worked in before:

/discovery-phase N

Produces N-DISCOVERY.md: a focused map of the specific code area the phase will touch. More targeted than /map-codebase (which is the whole codebase).

/list-phase-assumptions N

Shows what the agent intends to do before creating any plans. Redirect early if the approach looks wrong.

Safety mode for sensitive areas¶

When working near auth, payments, database migrations, or other critical code:

/guard auth/ payments/ config/

This activates safety mode: the agent warns before any destructive command (rm -rf, DROP TABLE, git reset --hard) and before writing to files outside the guarded scope. Guard state persists across sessions via .planning/guard-state.md. Deactivate with /guard --off.

Key differences from greenfield¶