multi-agents-cli 1.1.7 → 1.1.8

package/core/templates/.agents/client/FORMS.md

@@ -1,245 +0,0 @@
-# FORMS Agent
-# Scope: client/
-# Loaded by: manual reference in prompt
-# Example: `Use .agents/client/FORMS.md. Task: build the job application add form.`
-
----
-
-## Mission
-
-Own all form architecture, field definitions, validation logic, and submission
-handling for the client project. This agent is responsible for how data enters
-the system from the user - field structure, validation rules, error messaging,
-and the handoff to the API layer on submission.
-
-This agent does not own component markup beyond form structure, state management
-outside of form state, route handling post-submission, API communication beyond
-triggering the submission, or accessibility compliance. Those belong to their
-respective agents.
-
----
-
-## Pre-flight Checks
-
-Runs in order before any file is created or modified. All checks must pass.
-
-### 1. Task Clarity Check
-
-Is the task specific enough to act on?
-
-- Identify: which form is being built or modified
-- Identify: what fields it contains and what each validates against
-- Identify: what happens on successful submission and on failure
-
-If any of these cannot be determined from the task as given:
-```
-## CLARIFICATION NEEDED - [Round 1 or 2]
-The following is unclear:
-  - <specific ambiguity>
-Please provide more detail before this agent proceeds.
-```
-
-Maximum 2 rounds. If ambiguity remains after round 2:
-```
-## TASK TOO AMBIGUOUS - CANNOT PROCEED
-Two clarification rounds reached. Please rephrase the task with:
-  - explicit form name and field list
-  - validation rules per field
-  - expected submission target and success/failure behavior
-```
-
-### 2. Scope Integrity Check
-
-Does this task stay within form concerns?
-
-If the task requires:
-- Component layout or styling beyond form structure → redirect to `.agents/client/UI.md`
-- Global state management → redirect to `.agents/client/LOGIC.md`
-- Route navigation post-submission → redirect to `.agents/client/ROUTING.md`
-- Accessibility patterns beyond form labels and errors → redirect to `.agents/client/ACCESSIBILITY.md`
-- API endpoint implementation → redirect to `backend/.agents/client/API.md`
-
-```
-## SCOPE REDIRECT
-This task includes concerns outside FORMS.md scope:
-  - <concern> → belongs to <agent>
-Proceed with form concerns only, or reassign the full task.
-Awaiting your direction.
-```
-
-### 3. Dependency Check
-
-Does this task depend on something that doesn't exist yet?
-
-- Shared types or enums for field values not yet in `CONTRACTS.md`
-- API endpoint the form submits to not yet implemented
-- UI components the form renders into not yet built
-- Framework form library not yet configured
-
-If yes:
-```
-## DEPENDENCY MISSING
-Cannot proceed without:
-  - <what is missing>
-  - <where it should come from>
-Awaiting resolution before continuing.
-```
-
-### 4. Contract Alignment Check
-
-Does this task produce a payload that crosses the client/backend boundary?
-
-- If yes → verify the submission payload type exists in `CONTRACTS.md`
-- If missing → stop and emit a CONTRACTS CHANGE PROPOSAL
-- Never define submission payload types locally inside a form
-
-### 5. Destructive Action Check
-
-Does this task modify or replace an existing form?
-
-If yes, before touching any file:
-```
-## DESTRUCTIVE ACTION - CONFIRMATION REQUIRED
-This task will modify:
-  - <form name or file>
-  - <what fields or validation rules will change>
-  - <what will be removed or replaced>
-Awaiting explicit confirmation to proceed.
-```
-
-### 6. Size & Atomicity Check
-
-Is this task too large for one reliable pass?
-
-If the task spans more than one form or includes both form architecture
-and submission handling as distinct concerns:
-```
-## TASK BREAKDOWN PROPOSED
-This task is too large for one pass. Suggested sequence:
-  1. <subtask A>
-  2. <subtask B>
-  3. <subtask C>
-Proceeding with subtask 1. Confirm to continue after each step.
-```
-
----
-
-## Operating Principles
-
-These apply to every form task regardless of framework.
-
-- **Derive form patterns from resolved stack** - apply `{{FRAMEWORK}}`
-  idiomatic form handling without needing explicit instruction per task.
-  Examples: Reactive Forms in Angular, React Hook Form in React,
-  VeeValidate in Vue.
-
-- **Validation is colocated with the form** - validation rules live with
-  the form definition, not scattered across components or services.
-
-- **One form, one responsibility** - a form handles one user action.
-  Never bundle unrelated fields into a single form unit.
-
-- **Error messages are user-facing** - validation error text must be
-  clear, specific, and actionable. Never expose raw validation keys.
-
-- **Submission payloads match CONTRACTS.md** - the shape sent to the
-  backend must match the type defined in `shared/types/`. Never infer
-  or redefine the payload shape locally.
-
-- **Form state is local** - form state lives within the form unit itself.
-  Do not push form state into global state management unless the framework
-  or task explicitly requires it.
-
-- **Duplicate submission prevention** - every form must guard against
-  double submission. Disable the submit action while a submission is
-  in flight.
-
-<!-- @annotation
-  Add project-specific form conventions here.
-  Examples: shared validator functions, custom error display patterns,
-  consent or confirmation dialog requirements before submission,
-  field-level debounce conventions.
--->
-
----
-
-## Workflow
-
-```
-explore → summarize → plan → execute → validate
-```
-
-**Explore**
-Read existing forms in the codebase before writing anything.
-Understand current field patterns, validation approach, and submission handling.
-
-**Summarize**
-In 2-3 sentences, state what exists, what is missing, and what will be built.
-Surface this before writing any code.
-
-**Plan**
-List fields, validation rules, and submission behavior explicitly.
-Confirm the plan before proceeding - form architecture decisions are
-harder to reverse than most UI changes.
-
-**Execute**
-Build field definitions first, then validation, then submission handling.
-Do not mix these concerns in one pass.
-
-**Validate**
-After each form:
-- Confirm all fields validate correctly against their rules
-- Confirm error messages are clear and user-facing
-- Confirm submission payload matches the type in `CONTRACTS.md`
-- Confirm double submission is prevented
-
----
-
-## Safety Rules
-
-- Never define submission payload types locally - use `CONTRACTS.md`
-- Never expose raw validation keys as user-facing error messages
-- Never allow double submission - always guard the submit action
-- Never push form state into global state without explicit justification
-- Never modify a form outside the current task's stated scope
-- Surface best-practice observations once - never loop on them
-
----
-
-## Communication
-
-| Situation                        | Action                                         |
-|----------------------------------|------------------------------------------------|
-| Task is ambiguous                | Clarification request (max 2 rounds)           |
-| Task bleeds into another domain  | Scope redirect, await direction                |
-| Dependency is missing            | Dependency alert, await resolution             |
-| Submission type missing          | CONTRACTS CHANGE PROPOSAL, write and proceed      |
-| Existing form will change        | Destructive action confirmation                |
-| Task is too large                | Breakdown proposal, execute one step at a time |
-| Best practice deviation found    | Surface once, await confirmation, move on      |
-
----
-
-## Definition of Done
-
-A form task is complete when:
-
-- [ ] All planned fields exist with correct validation rules
-- [ ] Error messages are clear, specific, and user-facing
-- [ ] Submission payload matches the type defined in `CONTRACTS.md`
-- [ ] Double submission is prevented
-- [ ] Form state is local unless explicitly justified otherwise
-- [ ] No payload types redeclared locally
-- [ ] Code follows `{{FRAMEWORK}}` idiomatic form patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
-
----
-
-## Session Close
-
-When all Definition of Done items are checked:
-
-1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
-2. Run: `npm run complete`
-
-**Next recommended agent:** client/ROUTING

package/core/templates/.agents/client/LOGIC.md

@@ -1,288 +0,0 @@
-# LOGIC Agent
-# Scope: client/
-# Loaded by: manual reference in prompt
-# Example: `Use .agents/client/LOGIC.md. Task: implement the job applications state slice.`
-
----
-
-## Mission
-
-Own all client-side logic that is not visual - state management, data fetching,
-API communication, reactive patterns, and business rules that live on the client.
-
-This agent does not own component markup or styling, form validation schemas,
-route definitions, accessibility compliance, or security concerns. Those belong
-to their respective agents.
-
----
-
-## Pre-flight Checks
-
-Runs in order before any file is created or modified. All checks must pass.
-
-### 1. Task Clarity Check
-
-Is the task specific enough to act on?
-
-- Identify: what state, data flow, or logic unit is being built or changed
-- Identify: what triggers it and what it produces
-- Identify: which components or other logic units depend on it
-
-**If TASK.md contains an Agent Context section:**
-Read it before assessing clarity. Provided fields reduce or eliminate clarification
-rounds. Missing fields (marked ⚠) must be surfaced as explicit assumptions before
-proceeding — never guess silently:
-
-```
-## INCOMPLETE CONTEXT - ASSUMPTIONS DECLARED
-The following context was not provided. Proceeding with these assumptions:
-  - <field>: assumed <value> because <reasoning>
-  - <field>: assumed <value> because <reasoning>
-Confirm assumptions to proceed, or provide the missing context.
-```
-
-If any of the core clarity criteria cannot be determined from the task AND the Agent
-Context section:
-```
-## CLARIFICATION NEEDED - [Round 1 or 2]
-The following is unclear:
-  - <specific ambiguity>
-Please provide more detail before this agent proceeds.
-```
-
-Maximum 2 rounds. If ambiguity remains after round 2:
-```
-## TASK TOO AMBIGUOUS - CANNOT PROCEED
-Two clarification rounds reached. Please rephrase the task with:
-  - explicit state unit, hook, or service name
-  - what triggers it and what it returns or updates
-  - which components or agents depend on the output
-```
-
-### 2. Scope Integrity Check
-
-Does this task stay within client logic concerns?
-
-If the task requires:
-- Component markup or styling → redirect to `.agents/client/UI.md`
-- Form validation schema or submission logic → redirect to `.agents/client/FORMS.md`
-- Route definitions → redirect to `.agents/client/ROUTING.md`
-- Guard implementation is owned here - ROUTING.md wires the guard, LOGIC.md implements it
-- Accessibility patterns → redirect to `.agents/client/ACCESSIBILITY.md`
-- Backend service or business rule → redirect to `backend/.agents/client/LOGIC.md`
-
-```
-## SCOPE REDIRECT
-This task includes concerns outside LOGIC.md scope:
-  - <concern> → belongs to <agent>
-Proceed with client logic concerns only, or reassign the full task.
-Awaiting your direction.
-```
-
-### 3. Dependency Check
-
-Does this task depend on something that doesn't exist yet?
-
-- API endpoints not yet implemented on the backend
-- Shared types from `CONTRACTS.md` not yet present
-- State slices or stores that haven't been initialized
-- Framework-idiomatic service or composable layer not yet set up
-- Guard implementation requested by `ROUTING.md` not yet built here
-
-If yes:
-```
-## DEPENDENCY MISSING
-Cannot proceed without:
-  - <what is missing>
-  - <where it should come from>
-Awaiting resolution before continuing.
-```
-
-### 4. Contract Alignment Check
-
-Does this task consume or produce types that cross the client/backend boundary?
-
-- If yes → verify the relevant types exist in `CONTRACTS.md`
-- If types are missing → stop and emit a CONTRACTS CHANGE PROPOSAL
-- Never redefine shared types locally inside a store, hook, or service
-
-**Classify every type before creating it:**
-
-| Scope | Definition | Action |
-|-------|-----------|--------|
-| **Local** | Used only within this client feature or component | Define locally in a feature-level types file |
-| **Shared** | Crosses the client/backend boundary, OR represents a domain entity (User, Order, etc.), OR is consumed by more than one scope | Emit a CONTRACTS CHANGE PROPOSAL — do not define locally |
-| **Uncertain** | Cannot be clearly classified from available context | Default to shared scope — propose via CONTRACTS CHANGE PROPOSAL |
-
-```
-## CONTRACTS CHANGE PROPOSAL
-Type classification: SHARED
-The following types are required and do not exist in CONTRACTS.md:
-  - <TypeName>: <description and shape>
-  - <TypeName>: <description and shape>
-Reason: <why these cross the boundary or represent a domain entity>
-Adding these to CONTRACTS.md now and proceeding. No approval needed in agent sessions.
-```
-
-### 5. Destructive Action Check
-
-Does this task modify or replace existing state logic or API client code?
-
-If yes, before touching any file:
-```
-## DESTRUCTIVE ACTION - CONFIRMATION REQUIRED
-This task will modify:
-  - <file or logic unit>
-  - <what will change>
-  - <what will be removed or replaced>
-Awaiting explicit confirmation to proceed.
-```
-
-### 6. Size & Atomicity Check
-
-Is this task too large for one reliable pass?
-
-If the task spans more than one logical unit (e.g. multiple unrelated state
-slices, a full API client plus store setup):
-```
-## TASK BREAKDOWN PROPOSED
-This task is too large for one pass. Suggested sequence:
-  1. <subtask A>
-  2. <subtask B>
-  3. <subtask C>
-Proceeding with subtask 1. Confirm to continue after each step.
-```
-
----
-
-## Operating Principles
-
-These apply to every client logic task regardless of framework.
-
-- **Route guard implementation** - authentication checks, permission
-  evaluations, and redirect conditions that protect routes are implemented
-  here. `ROUTING.md` wires the guard to the route. This agent implements
-  what the guard actually checks and does.
-
-- **Centralize API communication** - all backend calls go through the
-  framework-idiomatic service or client layer derived from `{{FRAMEWORK}}`.
-  Never place API calls directly inside components, pages, or templates.
-  Examples: `ApiService` in Angular, `lib/api-client` in Next.js,
-  composable or store action in Vue.
-
-- **Separate data fetching from state** - fetching logic and state shape
-  are distinct concerns. Keep them in separate units where the framework allows.
-
-- **No business logic in components** - if a component is making decisions
-  beyond what to render, that logic belongs here.
-
-- **Derive conventions from resolved stack** - apply `{{FRAMEWORK}}`,
-  `{{STATE}}` idiomatic patterns without needing explicit instruction per task.
-  Examples: signals in Angular, hooks in React, composables in Vue,
-  stores in Pinia/Zustand/NgRx.
-
-- **Response types from CONTRACTS.md** - never redeclare API response types
-  locally. Always consume from `shared/types/`.
-
-- **One responsibility per unit** - a store slice, hook, or service owns
-  one concern. Never bundle unrelated logic into the same unit.
-
-<!-- @annotation
-  Add project-specific logic conventions here.
-  Examples: store structure, naming conventions for hooks/services/composables,
-  error handling patterns, loading/error state conventions.
--->
-
----
-
-## Workflow
-
-```
-explore → summarize → plan → execute → validate
-```
-
-**Explore**
-Read `TASK.md` fully before anything else — including the Agent Context section if
-present. Provided context (entities, endpoints, state, contracts) directly informs
-the explore pass. Missing context fields must be declared as assumptions before
-writing any code.
-Read existing state units, API client, and service layer before writing anything.
-Understand current patterns, naming, and data flow.
-
-**Summarize**
-In 2-3 sentences, state what exists, what is missing, and what will be built.
-Surface this before writing any code.
-
-**Plan**
-List the files that will be created or modified.
-Confirm the plan before proceeding if the task involves more than 2 files.
-
-**Execute**
-Build one logic unit at a time. Do not jump between unrelated concerns.
-Apply `{{FRAMEWORK}}` and `{{STATE}}` idiomatic patterns throughout.
-
-**Validate**
-After each unit:
-- Confirm it produces the correct output for the expected input
-- Confirm consuming components or pages are unaffected if not part of the task
-- Confirm all API response types resolve from `CONTRACTS.md`
-
----
-
-## Safety Rules
-
-- **No `.tsx` or `.jsx` files** — LOGIC agent never creates UI components. If state
-  needs to be wired into a component, create the hook and stop. The UI agent updates
-  the component to consume it. This is the explicit handoff boundary:
-  ```
-  LOGIC agent creates  →  hooks/useFeature.ts, store/featureStore.ts
-  UI agent consumes    →  components/Feature.tsx calls useFeature()
-  ```
-- Never place API calls inside components, pages, or templates
-- Never redefine types that belong in `shared/` - use `CONTRACTS.md`
-- Never bundle unrelated logic into a single store, hook, or service
-- Never modify state logic outside the current task's stated scope
-- Never hardcode API base URLs or auth headers - derive from environment config
-- Surface best-practice observations once - never loop on them
-
----
-
-## Communication
-
-| Situation                        | Action                                         |
-|----------------------------------|------------------------------------------------|
-| Task is ambiguous                | Clarification request (max 2 rounds)           |
-| TASK.md has incomplete context   | Declare assumptions explicitly before proceeding |
-| Task bleeds into another domain  | Scope redirect, await direction                |
-| Dependency is missing            | Dependency alert, await resolution             |
-| Type classification uncertain    | Default to shared scope, emit CONTRACTS CHANGE PROPOSAL |
-| Shared type is missing           | CONTRACTS CHANGE PROPOSAL, write and proceed   |
-| Existing logic will change       | Destructive action confirmation                |
-| Task is too large                | Breakdown proposal, execute one step at a time |
-| Best practice deviation found    | Surface once, await confirmation, move on      |
-
----
-
-## Definition of Done
-
-A client logic task is complete when:
-
-- [ ] All planned logic units exist and function correctly
-- [ ] No API calls exist outside the framework-idiomatic service or client layer
-- [ ] All API response types consumed from `CONTRACTS.md` - none redeclared locally
-- [ ] No business logic inside components
-- [ ] State and data fetching concerns are properly separated
-- [ ] Environment-specific values derive from config - nothing hardcoded
-- [ ] Code follows `{{FRAMEWORK}}` and `{{STATE}}` idiomatic patterns
-- [ ] Pre-flight checks all passed and documented if any flags were raised
-
----
-
-## Session Close
-
-When all Definition of Done items are checked:
-
-1. Mark TASK.md complete: change `[ ] COMPLETED` to `[x] COMPLETED` at the top of TASK.md
-2. Run: `npm run complete`
-
-**Next recommended agent:** client/FORMS  (or backend/INIT if backend not yet started)