You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+117Lines changed: 117 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -97,6 +97,9 @@ Detailed rules are in the domain documents. Summary of responsibility:
97
97
-**Instantiation**: when starting a new project from the framework, consult `FCVW/INSTANTIATION.md`; do not use recursive scripts to rename or replace content in batch without explicit review of the affected files.
98
98
-**Security**: `FCVW/SECURITY.md` — validate path traversal in any workflow that reads or writes paths coming from the UI or backend.
99
99
-**Terminal Restrictions (Sandboxing)**: It is strictly forbidden to install global dependencies (e.g., `-g`) or modify system/environment configurations outside the workspace directory without explicit human approval.
100
+
-**Third-Party Services**: whenever a task requires choosing or integrating a third-party developer service (database, auth, payments, hosting, email, cache, monitoring, analytics, AI, storage, CMS, search, realtime, background jobs, infrastructure, or any external API), research available options, compare them against project constraints, and document the reasoning before implementation. Never recommend or integrate a service from memory alone. Consult `FCVW/AI.md §Third-Party Service Research` for detailed rules.
101
+
-**Code Review / Pull Requests**: every plan execution that results in a branch push must be proposed as a Pull Request. R3+ plans require at least one reviewer before merge. See the "Code Review and Pull Requests" section below for the full workflow.
102
+
-**Multi-Agent Concurrency**: before starting any plan, check `FCVW/Plans/in_progress/` for active plans that may overlap with your scope. If a collision is detected, coordinate via agent journals before proceeding. See the "Multi-Agent Concurrency" section below for the full protocol.
100
103
101
104
## Initial Checklist
102
105
@@ -115,6 +118,7 @@ Before executing a request that might modify files:
115
118
- if no plan exists, create one before editing;
116
119
- classify the plan using priority, risk, operational score, review gate, rollback requirement, and decomposition requirement before starting execution;
117
120
- for bugs, consult `FCVW/troubleshooting/` before proposing a fix;
121
+
- for third-party service selection or integration, consult `FCVW/AI.md §Third-Party Service Research` before recommending or integrating;
118
122
- for visual changes, consult `FCVW/DESIGN.md`;
119
123
- for version, release, or changelog changes, consult `FCVW/VERSIONING.md`;
120
124
- for release, consult `FCVW/RELEASE.md`;
@@ -129,6 +133,7 @@ Before executing a request that might modify files:
129
133
- for reusable learnings, consult `FCVW/wiki/index.md`;
130
134
- for agent-specific journals, use `FCVW/wiki/agents/<agent_name>_journal.md`;
131
135
-**Knowledge Interconnection**: when creating or updating documents in `FCVW/wiki/` or `FCVW/decisions/`, the AI should actively seek to create links between related concepts to feed the connection graph (Obsidian Graph View);
136
+
- for multi-agent coordination, check `FCVW/Plans/in_progress/` for overlapping scope before creating or starting a new plan;
132
137
- confirm which files are within scope;
133
138
- identify pre-existing changes that should not be reverted.
134
139
@@ -148,6 +153,116 @@ Before executing a request that might modify files:
148
153
149
154
If a necessary change is not covered by the plan, create or update a plan before implementing.
150
155
156
+
## Code Review and Pull Requests
157
+
158
+
Every plan execution that produces a branch with modified files must be submitted as a Pull Request before the changes are considered final. This section defines the workflow for branch creation, PR submission, review, and merge.
159
+
160
+
### Branch Naming
161
+
162
+
Use descriptive, hierarchical branch names that identify the type and scope of work:
163
+
164
+
```text
165
+
<type>/<scope>/<short-description>
166
+
```
167
+
168
+
Examples:
169
+
170
+
```text
171
+
feat/auth/login-screen
172
+
fix/api/null-pointer-on-empty-response
173
+
refactor/orders/introduce-parameter-object
174
+
docs/FCVW/service-research-rules
175
+
```
176
+
177
+
### Pull Request Workflow
178
+
179
+
1.**Create branch** from the main development branch using the naming convention above.
180
+
2.**Implement changes** according to the plan scope. Commit incrementally with semantic messages.
181
+
3.**Open Pull Request** targeting the main development branch. The PR description must include:
- R1-R2 plans: self-review acceptable (use `skill:governance-validator` for confidence)
189
+
- R3 plans: at least 1 peer reviewer
190
+
- R4 plans: at least 2 reviewers, including module owner or technical lead
191
+
- R5 plans: human approval required before merge (per `PLANNING.md`)
192
+
5.**Address feedback**: make additional commits to the same branch. Do not rebase or force-push after review has started.
193
+
6.**Merge**: after approval, merge using squash or merge commit (team preference). Do not merge if automated tests or validations fail (or have not been run), there are unresolved conflicts, or the scope grew without plan update.
194
+
195
+
### Code Review Standards
196
+
197
+
Reviewers must verify:
198
+
199
+
- The change matches the plan scope exactly.
200
+
- No unplanned functional changes were introduced.
201
+
- External behavior described as preserved is indeed preserved (refactoring only).
202
+
- Tests exist or the limitation is documented in the plan.
203
+
- Security, data, and configuration changes follow `FCVW/SECURITY.md`, `FCVW/DATA.md`, and `FCVW/ENVIRONMENT.md`.
204
+
- The changelog fragment exists in `FCVW/changelogs/unreleased/`.
205
+
- No secrets, credentials, or sensitive data are exposed.
This document provides: PR size guidance by risk, mandatory PR content fields, approval matrix by risk, merge blocking conditions, and chained PR workflow for incremental refactorings.
213
+
214
+
## Multi-Agent Concurrency
215
+
216
+
This section defines the protocol for multiple AI agents or human developers working simultaneously in the same repository. The framework presumes serial single-agent operation by default — when two or more contributors operate concurrently, they must follow this coordination protocol to prevent collisions.
217
+
218
+
### Core Principle: Plan-Based Signaling
219
+
220
+
The `Plans/` directory is the coordination bus. The presence of a plan file in `Plans/in_progress/` signals "an agent is working on this scope." Agents must read this directory before starting work and respect active plans.
221
+
222
+
### Pre-Work Coordination Check
223
+
224
+
Before creating a new plan or starting execution:
225
+
226
+
1.**List active plans**: Read all files in `FCVW/Plans/in_progress/`. For each plan, note the **scope**, **affected files**, and **agent/author**.
227
+
2.**Detect collision**: Compare your intended scope against each active plan. A collision exists if:
228
+
- You intend to modify the same file(s) as an active plan.
229
+
- You intend to modify the same module, component, or functional area.
230
+
- Your changes could semantically conflict (e.g., renaming a function another plan is adding callers to).
231
+
3.**Assess overlap**: If a collision is found:
232
+
-**Low overlap** (different files in the same module): proceed but note the adjacent work in your plan.
233
+
-**Medium overlap** (same file, different functions): coordinate via agent journal before proceeding.
234
+
-**High overlap** (same functions, contracts, or data structures): one agent should wait — compare priority (P1 > P2 > ...) and defer the lower-priority plan.
235
+
4.**Signal your plan**: Before starting execution, ensure your plan is in `Plans/in_progress/` with a clearly defined `scope` and `context_files` list so other agents can detect collision with your work.
236
+
237
+
### Agent Journals as Coordination Channels
238
+
239
+
Agent journals in `FCVW/wiki/agents/` serve as asynchronous coordination channels:
240
+
241
+
-**Agent A** working on module X leaves a journal entry at `FCVW/wiki/agents/agent_a_journal.md` describing the active scope, expected duration, and affected files.
242
+
-**Agent B** checking for collisions reads the journal, notes the overlap, and decides whether to defer, split scope, or coordinate.
243
+
- Journals are append-only. Each entry must include a timestamp and the current plan filename.
244
+
245
+
### Scope Locking Convention
246
+
247
+
A plan in `Plans/in_progress/` creates an **implicit soft lock** on the files listed in its `context_files` frontmatter. Other agents should not modify those files without explicit coordination. The lock is released when the plan moves to `Plans/completed/` or `Plans/discontinued/`.
248
+
249
+
This is a convention, not a technical lock — it relies on agents following the protocol. Git provides the hard safety net via merge conflict detection.
250
+
251
+
### Conflict Resolution
252
+
253
+
If two agents independently modify the same files and a Git merge conflict occurs:
254
+
255
+
1.**Do not force-push or overwrite.** Stop and assess.
256
+
2.**Identify the conflicting plan** by checking which other plan touches the conflicted files.
257
+
3.**Communicate** via the respective agent journals documenting the conflict, the attempted resolution, and the outcome.
258
+
4.**Resolve** using standard Git conflict resolution. Preserve both intents when possible.
259
+
5.**Update plans** affected by the conflict to reflect the resolution.
260
+
6.**Record the event** in `troubleshooting/` as a learning for future concurrency.
261
+
262
+
### Branch Isolation
263
+
264
+
When working concurrently, each agent should use its own branch per the branch naming convention in "Code Review and Pull Requests." This keeps concurrent work isolated until PR review and merge, reducing the chance of mid-work collisions.
265
+
151
266
## Checklist Before Finishing a Change
152
267
153
268
> This checklist covers technical and document execution. It is the mandatory standard for closing shifts that modify files. For pre-release auditing, consult `FCVW/AUDIT.md`.
@@ -159,7 +274,9 @@ If a necessary change is not covered by the plan, create or update a plan before
159
274
- If there was a visual change, does `FCVW/DESIGN.md` reflect the current state?
160
275
- If there was a bug, was `FCVW/troubleshooting/` consulted or updated?
161
276
- Has the changelog fragment been created in `unreleased/` and does it cite the altered files?
277
+
- Has the Pull Request been reviewed and approved according to the risk classification (R3+ requires at least one reviewer)?
162
278
-**AI Context Compression**: has a new chronological session synthesis been created in [`FCVW/wiki/sessions/`](FCVW/wiki/sessions/) following the template to compress context for the next session?
163
279
- Were tests executed or has the limitation been recorded?
164
280
- Were temporary files, logs, and private data left out of versioning?
165
281
- Was the final state clearly described to the user?
282
+
- Has the plan been moved to `completed/` or `discontinued/`, releasing the soft lock for other agents?
Copy file name to clipboardExpand all lines: FCVW/AI.md
+39Lines changed: 39 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -192,6 +192,45 @@ skills_invoked:
192
192
- "skills/obsidian-markdown/SKILL.md"
193
193
```
194
194
195
+
## Third-Party Service Research
196
+
197
+
To prevent the AI agent from recommending outdated, insecure, or inappropriate third-party services based solely on training memory, the following rules apply whenever a task involves selecting or integrating an external service (database, auth, payments, hosting, email, cache, monitoring, analytics, AI, storage, CMS, search, realtime, background jobs, infrastructure, SMS, video, webhooks, or any external API).
198
+
199
+
### Mandatory Research
200
+
201
+
Before recommending or integrating any third-party service, the AI agent must:
202
+
203
+
1. **Discover available options**: Use available research tools to identify potential providers for the required capability. Do not rely on memory alone.
204
+
2. **Compare against constraints**: Evaluate each option against the project's explicit constraints documented in `STACK.md`, `SCOPE.md`, `PERFORMANCE.md`, `SECURITY.md`, and `DATA.md`. Consider: free-tier limits, pricing model, data residency, latency, maintenance burden, community health, API stability, and compatibility with the existing stack.
205
+
3. **Document reasoning**: Record the selected service, the alternatives considered, and the rationale for the choice. This documentation lives in the active plan, an ADR in `decisions/`, or a wiki page in `wiki/decisions/`.
206
+
4. **Install and configure**: Follow the service's official documentation for setup. Use the project's `.env.example` to document required environment variables (following `ENVIRONMENT.md` rules). Never hardcode credentials.
207
+
208
+
### Prohibited Behavior
209
+
210
+
- **Never** recommend a service based solely on the AI's training data without verifying current status, pricing, documentation, and compatibility.
211
+
- **Never** assume a specific SDK version, endpoint, or API contract without checking the official documentation.
212
+
- **Never** fall back to placeholder or faux services without explicit user consent and a plan to replace them.
213
+
- **Never** skip research because the service seems "obvious" or "standard" — common services change terms, pricing, and APIs frequently.
214
+
215
+
### Integration Protocol
216
+
217
+
When a third-party service requires API credentials:
218
+
219
+
1. Create the target environment variable in `.env.local` (e.g., `SERVICE_API_KEY=`).
220
+
2. Update `.env.example` with the new variable name, type, and placeholder value.
221
+
3. Instruct the user to paste the secret into `.env.local` (per the Secret Handshake protocol in `SECURITY.md`).
222
+
4. Do not proceed with integration until the user confirms credentials are in place.
223
+
224
+
### Exceptions
225
+
226
+
Research may be skipped only when:
227
+
228
+
- The service is already integrated and documented in the project (verify via `STACK.md`, existing configuration, or imports).
229
+
- The user explicitly specifies the exact provider, version, and configuration to use.
230
+
- The task is a direct bugfix or upgrade of an already-integrated service.
231
+
232
+
In all exceptions, verify the existing integration is still current and supported before proceeding.
0 commit comments