AI Development¶
This is the AI/control layer that supports the flow described in How Engineering Works — how Claude actually gets invoked day to day at DragonPay: which mode to use, what each mode produces, and how work moves from a Claude session into something accepted, verified, and released. It is not a restatement of the whole engineering model — see How Engineering Works for that. The authoritative underlying spec is ENG-02 §3 (Operating modes); this page is the practical, human-facing quick reference built on top of it.
Golden rule
Choose the mode for the action you want. Claude may recommend another mode, but it does not switch modes or cross repository authority boundaries on its own.
1. Which mode do I use?¶
| Mode | Use it when... | Primary output | Typical prompt |
|---|---|---|---|
| PM Mode | Changing or clarifying what DragonPay intends to build. | Approved Product requirement / standard / Product ADR updates. | "PM Mode. Review [issue] and propose the Product changes needed. Do not edit until I approve." |
| ENG Mode | Making engineering decisions or building a Product/Foundation requirement. | Plan, code, tests, implementation evidence, ADR recommendation/setup. | "ENG Mode. Work [REQ-ID]. Resolve context, identify issues, and give me the plan before coding." |
| Admin Mode | Refreshing visibility and deciding what needs attention next. | Updated indexes/status/attention views/MkDocs. | "Admin Mode. Refresh DragonPay and tell me what needs attention." |
2. PM Mode — change what we intend to build¶
Purpose: Maintain authoritative Product intent as requirements evolve through feedback, discovery, and development.
May update: PH / PP / CX / OX / CI / ENG / STD requirements, Product ADRs, and Product relationship metadata when explicitly authorized.
Does not mean: Claude may rewrite Product requirements during an ENG task. PM Mode must be explicitly invoked.
PM Mode workflow
- Identify the feedback, ambiguity, conflict, missing decision, or new capability.
- Find the affected requirements and related Product context.
- Assess cross-story / cross-document impact.
- Propose the smallest coherent Product change.
- Present changes and impacts for human approval.
- After approval, update the Product repository and validate consistency.
Use PM Mode after ENG findings: ENG Mode may record an attention item
such as REQUIREMENT_AMBIGUITY or MISSING_PRODUCT_DECISION. You later
invoke PM Mode to address it. There is no automatic handoff.
3. ENG Mode — decide how and build it¶
Purpose: Perform foundation/ADR work and implement PRODUCT-class or FOUNDATION-class requirements.
Product repository: Read-only during the ENG action. Claude may identify needed Product changes but cannot make them.
Foundation decisions: Remain ENG work. Claude may evaluate options and draft a recommendation/ADR. Human approval is required before a choice becomes authoritative.
ENG Mode workflow
| Step | Action | Meaning |
|---|---|---|
| 1 | Select work | Start from a requirement/work ID where possible. |
| 2 | Resolve context | Load applicable Product, STD, ENG, ADR, code, tests, traceability, and protected existing requirements. |
| 3 | Preflight | Return READY, READY_WITH_ISSUES, or BLOCKED. |
| 4 | Plan review | Claude provides a concise implementation plan. Engineer reviews before coding during early DragonPay development. |
| 5 | Build locally | Claude implements only the selected work and the minimum required scaffolding. |
| 6 | Claude self-validation | Run applicable build/lint/tests/security/traceability checks. |
| 7 | Engineer implementation review | Engineer reviews behavior, code, tests, Product fit, architecture, assumptions, and maintainability; iterate as needed. |
| 8 | Source-control acceptance | Reviewed implementation is accepted into the configured authoritative Development branch. |
| 9 | IMPLEMENTED |
Derived from source-control acceptance; not from Claude or a YAML claim. |
| 10 | VERIFIED / RELEASED |
Later derived from automated verification and qualifying PROD deployment evidence. |
What Claude should give the engineer before acceptance
- What changed and which files/packages were affected.
- How the requirement objective and acceptance criteria are satisfied.
- Applicable STD/ENG requirements and ADRs used.
- Other mapped requirements that could be affected and how they were protected.
- Tests/checks run and results.
- Decisions or assumptions made.
- Known issues, limitations, or attention items.
Preflight and issue handling
| Result | Meaning | Action |
|---|---|---|
READY |
No material unresolved issue prevents work. | Proceed. |
READY_WITH_ISSUES |
Issues exist, but meaningful safe work can continue. | Record issues; continue unaffected work. |
BLOCKED |
The affected current work cannot safely or meaningfully continue. | Stop only the affected work; record why. |
Important
Do not block an entire requirement because one acceptance criterion or unrelated requirement has an issue if useful safe work can continue.
4. Admin Mode — refresh the picture¶
Purpose: Keep Product/engineering visibility current so decisions do not depend on manually rereading random documents or code.
Standard action: "Admin Mode. Refresh DragonPay and tell me what needs attention."
Target command: dp-eng refresh
Admin refresh should eventually cover
- Product index refresh from the configured pinned Product checkout.
- Traceability and repository validation.
- Effective requirement/foundation status calculation.
- Attention-item / blocker views.
- Generated implementation and documentation views.
- MkDocs generated content and build/refresh.
- DEV / STA / PROD visibility when those environments exist.
When to run Admin Mode
- At the start of a meaningful work session.
- After Product requirements or ADRs are updated.
- After implementation / traceability changes.
- Before choosing the next work item.
- Before sharing MkDocs with executives or other stakeholders.
5. Attention items — what needs follow-up¶
Purpose: Persist findings so they are not lost in a prior Claude session.
| Issue type | Use | Typical next action |
|---|---|---|
REQUIREMENT_AMBIGUITY |
Product meaning is unclear. | Later invoke PM Mode. |
REQUIREMENT_CONFLICT |
Authoritative Product requirements conflict. | Later invoke PM Mode. |
MISSING_PRODUCT_DECISION |
Product decision is required. | Later invoke PM Mode. |
MISSING_ENGINEERING_DECISION |
Engineering/tool/architecture choice is missing. | Use ENG Mode foundation/ADR action. |
EXTERNAL_DEPENDENCY |
External prerequisite is missing. | Satisfy prerequisite; no automatic PM/ADR work. |
Rule: Claude may recommend the next mode/action, but you invoke it. No automatic mode switching.
6. Status quick reference¶
| Status | What it means | Determined by |
|---|---|---|
NOT_STARTED |
No active implementation. | Current work state. |
IN_PROGRESS |
Engineering work is underway. | Current work state / evidence. |
BLOCKED |
Affected work cannot meaningfully continue. | Recorded scoped blocker. |
IMPLEMENTED |
Reviewed implementation accepted into authoritative Development branch. | Source-control evidence. |
VERIFIED |
Accepted implementation passes required automated verification. | CI / verification evidence. |
RELEASED |
Verified implementation is present in PROD for all required deployment units. | Deployment evidence. |
Bootstrap note: While DragonPay is local-only, the configured
authoritative local Git branch may serve as the IMPLEMENTED acceptance
point. After a shared remote is established, the authoritative branch
should normally be the protected integration/default branch.
Not the Startup Checklist
This is the formal Product/Foundation requirement lifecycle. The
Setup Tasks & Checklists page uses a separate,
simpler NOT_STARTED | IN_PROGRESS | BLOCKED | DONE vocabulary scoped
only to 0→1 startup tasks — the two are deliberately not the same
system.
7. Fast prompts¶
| Action | Copy/paste prompt |
|---|---|
| PM | "PM Mode. Review [issue/requirement] and propose the smallest coherent Product update. Show impacted requirements and wait for my approval before editing." |
| ENG | "ENG Mode. Work [REQ-ID]. Resolve the applicable context, classify issues, and give me a concise implementation plan before coding." |
| ADMIN | "Admin Mode. Refresh DragonPay and tell me what needs attention, what changed, and what I should act on next." |
| FOUNDATION | "ENG Mode. Work [ENG-ID / engineering decision]. Evaluate options against DragonPay requirements, recommend an approach, and draft the decision for my review. Do not make it authoritative without approval." |
| PRODUCT ISSUE | "PM Mode. Review the open Product attention item for [REQ-ID], assess related requirements, and propose the required change. Wait for approval before editing." |
| RESUME | "ENG Mode. Resume [REQ-ID] using the current approved Product baseline and decisions. Re-run context/preflight before continuing." |
8. Do not forget¶
- PM Mode changes authoritative intent; ENG Mode decides/builds; Admin Mode refreshes visibility.
- Operating modes and requirement classes are separate concepts. ENG Mode can work on PRODUCT-class and FOUNDATION-class requirements.
- Claude does not autonomously switch modes.
- ENG Mode does not edit Product requirements.
- A finding does not automatically block all work; scope the issue to what it actually affects.
- Engineer review is required before source-control acceptance.
IMPLEMENTEDcomes from authoritative-branch acceptance, not from Claude saying "done."VERIFIEDandRELEASEDare system-derived evidence states.- MkDocs is the visibility/presentation layer, not the source of authority.