Creates DEVELOPMENT_PLAN.md with repo-rule compliance researched first (file placement, architecture, patterns). Use for new features, M/L work, or /plan. Not XS/S quick changes (quick-piv), product-only requirements (feature), or changelog updates (finish).
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Creates DEVELOPMENT_PLAN.md with repo-rule compliance researched first (file placement, architecture, patterns). Use for new features, M/L work, or /plan. Not XS/S quick changes (quick-piv), product-only requirements (feature), or changelog updates (finish).
plan
Create a development plan for a feature or job. Research how best to implement it, check repo rules, and produce DEVELOPMENT_PLAN.md in documentation/jobs/temp_job_<name>/.
Critical: Conflict and compliance is researched first; steps in each phase must reflect that (file placements, architecture, patterns). The plan documents how to implement according to repo rules.
Do NOT update the changelog. Changelog updates are done in the finish command, not during planning.
Related: For session context, use .agents/skills/prime/SKILL.md. For architecture/quality gate before merging, use .agents/skills/validate/SKILL.md (auto-selects gate depth). For small scoped work without a full plan file, use .agents/skills/quick-piv/SKILL.md. To execute this plan phase by phase, use .agents/skills/implement/SKILL.md. For repo-rule plan/impl review, use .agents/skills/validate/SKILL.md. For multi-lens plan critique (including industry precedent), use .agents/skills/review-dev-plan/SKILL.md. For industry precedent on plans/proposals, use .agents/skills/pattern-review/SKILL.md. For commits and changelog, use .agents/skills/finish/SKILL.md.
Flow
0. Branch gate (when plan will lead to code)
Verify current git branch. If on main or develop, stop — instruct: git switch develop + git pull origin develop, then git switch -c feature/<name> per .cursor/rules/workflow/RULE.md § Branch Strategy.
Planning may run on any branch; do not start file creation on main or develop.
1. Input
User describes what they want (e.g. add a capability, migrate X to Y).
Optional: job name, reference to spec or ticket.
2. Refine (if needed)
If the request is vague or unclear, do NOT write a plan yet.
Remove all ambiguity before planning. If multiple interpretations are possible, read documentation/DOC_APP_VISION.md first when the answer is about who the user is building for or why — if that file is still DRAFT, pause and have the user fill it (or confirm deferral) before locking scope.
Ask a question about the user's vision for how the app will be used, so the answer clears the ambiguity and drives the decision.
Continue until scope is clear.
Only proceed to investigation once scope is clear.
Optional: Requirements depth (complex or unfamiliar features)
For features involving external APIs, database changes, auth, or novel logic, gather typed requirements before investigating:
Feature type
Key info to confirm
API integration
Docs/URL, auth method, request/response format (real example), rate limits
Database change
Relevant schemas, related data patterns, RLS needs
UI component
Design ref or description, placement, responsive needs, interactive states
Completeness gate: Can you describe the exact expected behavior with concrete examples? If not, keep asking.
3. Investigate
Search the codebase for existing functionality to reuse (features under src/features/, shared under src/shared/, src/components/common/).
Identify relevant rules from .cursor/rules/ (start at .cursor/rules/INDEX.md).
Align narrative with documentation/DOC_APP_VISION.md when the plan changes user-facing behavior (problem, persona, app role); if DRAFT, pause for fill or explicit deferral.
For server-cached data, check documentation/DOC_TANSTACK_QUERY.md and existing api/keys.ts patterns in features.
Determine scope and boundaries (in-scope vs out-of-scope).
Feature decomposition self-check (mandatory): Enumerate distinct domain concepts this work introduces. If more than one cohesive bounded context applies, or projected file count exceeds featureBudgets.config.cjs defaults, plan multiple features under src/features/ before writing steps. Do not wait for the user to request architecture. See .cursor/rules/architecture/RULE.md § Feature granularity.
Optional: Foundation validation (high-risk features)
If the feature depends on an unproven assumption (new API, untested algorithm, novel integration):
Identify the riskiest assumption — what could invalidate the entire approach?
Test with a minimal POC (smallest possible proof: one API call, one query, one algorithm run).
Gate: Foundation works → proceed to plan. Foundation fails → report to user, investigate alternatives before planning.
Do not invest in full planning until the foundation is proven.
4. Create plan
Run conflict and compliance analysis first (see below).
Define phases in logical order (workable chunks).
Write steps per phase aligned with compliance (concrete paths, layers, patterns).
Proactively run .agents/skills/pattern-review/SKILL.md (plan-section mode) when Complexity is M or L, or the plan introduces new user-visible behavior/contracts (see rubric — agent chooses relevant aspects).
Fill Pattern & precedent in the plan. If non-standard, stop for owner pick (A/B/C or waiver) before implementation.
Industry / product precedent → pattern-review. Repo rules → Conflict & compliance and later validate.
6. Plan review gate
Set Plan review in Summary per dev-cycle matrix § Plan depth and gates — do not duplicate the M/L table here.
7. Present and iterate
Present the plan to the user.
Incorporate feedback and update the plan as needed.
Naming: Follow .cursor/rules/file-placement/RULE.md: folder temp_job_<descriptive-name>/ (kebab-case, descriptive). Allowed by projectStructure.config.cjs under documentation/jobs/ (nested *.md files).
Note: Older jobs in this repo may use other filenames (e.g. IMPLEMENTATION_PLAN.md); new plans from this command should standardize on DEVELOPMENT_PLAN.md.
Plan document structure
Mandatory sections (always include)
Section
Purpose
Content
Summary
Why and what, in brief
Goal, why, Complexity, Plan review status, scope, constraints
Phase overview
Table of all phases
Phase #, goal, gate, status
Conflict & compliance
Avoid technical debt, meet repo rules
See checklist below
Pattern & precedent
Industry / product patterns vs this design
See template; required for M/L; agent-chosen aspects
Notes during development
For implementation
Leave empty in the plan; fill during implementation
Decisions made
For implementation
Leave empty in the plan; fill during implementation
Per phase (repeat for each phase)
Phases must be in logical order and split into workable chunks. Each phase must have a gate.
Subsection
Required?
Content
Goal
Yes
What we achieve in this phase
Steps
Yes
Concrete steps aligned with conflict & compliance
Gate
Yes
How we validate this phase is complete
Optional sections (include when relevant)
Source/context – Where the request came from (feedback, ticket, etc.).
Validate planned file paths against projectStructure.config.cjs (whitelist); run pnpm validate:structure after structural additions if unsure.
Check architecture compliance: feature vs src/shared/ vs src/components/common/, layer boundaries, import direction (pages → hooks → services).
Feature decomposition self-check: List planned feature folder(s). If a single feature spans multiple domain concepts or exceeds featureBudgets.config.cjs budgets, split into separate features in the plan with narrow public APIs before listing file paths.
Identify any planned diversion from industry standards, framework best practices, or established repo conventions. If found, ask the user whether the diversion is intentional or whether the plan should align with best practices.
Estimate complexity (cyclomatic ≤10, cognitive ≤15, functions ≤100 lines per .cursor/rules/code-style/RULE.md); plan extractions if needed (see .agents/skills/optimize2/SKILL.md for refactoring workflow).
Note database impact if applicable (migrations under supabase/migrations/, idempotent, safe for fresh and existing DB).
Note security impact if applicable (auth, RLS, validation, secrets in .env only).
Document conflicts with existing code (pattern mismatches, breaking changes).
Consider testing: new or changed logic should have tests per .cursor/rules/testing/RULE.md.
Workflow: branch strategy per .cursor/rules/workflow/RULE.md (e.g. not developing on main). Changelog is updated in finish, not while planning.
If a feature’s behavior changes: plan updates to src/features/<feature>/README.md in the same work as code (see file-placement rule).
Output inside DEVELOPMENT_PLAN.md: A Conflict & compliance section with:
Applicable rules (by name/path).
Planned file placements and validation status (confirmed vs needs config change — config changes require explicit approval per architecture rule).
Known risks / attention points.
Open questions for the user.
Confirmed standards diversions, including whether the user chose to keep the diversion or align with best practices.
Refine first: If the request is vague, ask questions before writing the plan.
Ambiguity is not allowed: If ambiguity appears, ask about intended app usage or product vision before choosing.
Standards diversions are explicit: If a plan diverges from industry standards, best practices, or repo conventions, ask whether that is intentional before proceeding.
Phases are workable: Each phase is a logical, testable chunk.
Gates are mandatory: Every phase has a gate.
Compliance first: Conflict & compliance before detailed steps; steps must be rules-compliant.
Empty sections: Notes during development and Decisions made start empty.
