chore: bootstrap FUNDING.yml + AGENTS.md#507
Merged
Merged
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
CodeAnt AI is reviewing your PR. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAGENTS.md governance documentation was simplified, replacing comprehensive policies with concise instructions for the agentapi-plusplus project; FUNDING.yml was added or updated to configure GitHub sponsorship and a custom sponsor link. ChangesDocumentation Simplification
Sponsorship Configuration
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
|
codeant-ai
Bot
added
the
size:S
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
Bugbot Autofix is ON, but it could not run because on-demand usage is turned off. To enable Bugbot Autofix, turn on on-demand usage and set a spend limit in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit d01308b. Configure here.
| @@ -0,0 +1,2 @@ | |||
| github: [KooshaPari] | |||
| custom: ["https://kooshapari.com/sponsor"] | |||
There was a problem hiding this comment.
FUNDING.yml placed in root instead of .github directory
Medium Severity
The new FUNDING.yml is placed in the repository root, but GitHub only recognizes this file when it lives inside the .github/ directory. A .github/FUNDING.yml already exists in the repo (with github: KooshaPari). The root-level file will be silently ignored by GitHub, and the duplicate creates confusion about which configuration is authoritative.
Reviewed by Cursor Bugbot for commit d01308b. Configure here.
| ## Root-Level Files (Keep in Root) | ||
| ## AgilePlus Mandate | ||
| All work MUST be tracked in AgilePlus. | ||
| Reference: /Users/kooshapari/CodeProjects/Phenotype/repos/AgilePlus |
There was a problem hiding this comment.
Hardcoded local filesystem paths in agent instructions
Medium Severity
AGENTS.md contains absolute local filesystem paths (/Users/kooshapari/CodeProjects/Phenotype/repos/AgilePlus and /Users/kooshapari/CodeProjects/Phenotype/repos/CLAUDE.md) that are specific to one developer's machine. These references are non-functional for any other contributor or AI agent working in this repo, and they leak local directory structure into the public repository.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit d01308b. Configure here.
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
Comment on lines
+10
to
+13
| Reference: /Users/kooshapari/CodeProjects/Phenotype/repos/AgilePlus | ||
|
|
||
| Only these files should remain in the project root: | ||
| - `README.md` - Main project documentation | ||
| - `CHANGELOG.md` - Project changelog | ||
| - `AGENTS.md` - This governance file (AI agent instructions) | ||
| - `CLAUDE.md` / `claude.md` - Claude-specific instructions | ||
| - `00_START_HERE.md` - Getting started guide (if applicable) | ||
|
|
||
| ## Documentation Structure | ||
|
|
||
| All other `.md` files must be organized in `docs/` subdirectories: | ||
|
|
||
| ``` | ||
| docs/ | ||
| ├── guides/ # Implementation guides and how-tos | ||
| │ └── quick-start/ # Quick start guides | ||
| ├── reports/ # Completion reports, summaries, status reports | ||
| ├── research/ # Research summaries, indexes, analysis | ||
| ├── reference/ # Quick references, API references | ||
| └── checklists/ # Implementation checklists, verification lists | ||
| ``` | ||
|
|
||
| ## File Organization Rules | ||
|
|
||
| **When creating or moving documentation:** | ||
|
|
||
| ### 1. Quick Starts → `docs/guides/quick-start/` | ||
| - Files matching `*QUICK_START*.md` or `*QUICKSTART*.md` | ||
| - Examples: `GRAPH_OPTIMIZATION_QUICK_START.md`, `AUTH_ROUTES_QUICK_START.md` | ||
|
|
||
| ### 2. Quick References → `docs/reference/` | ||
| - Files matching `*QUICK_REFERENCE*.md` or `*QUICK_REF*.md` | ||
| - Examples: `NATS_QUICK_REFERENCE.md`, `CLI_QUICK_REFERENCE.md` | ||
|
|
||
| ### 3. Implementation Guides → `docs/guides/` | ||
| - Files matching `*IMPLEMENTATION_GUIDE*.md` or `*GUIDE*.md` | ||
| - General implementation documentation | ||
| - Examples: `API_IMPLEMENTATION_GUIDE.md`, `DEPLOYMENT_GUIDE.md` | ||
|
|
||
| ### 4. Completion Reports → `docs/reports/` | ||
| - Files matching `*COMPLETE*.md`, `*COMPLETION*.md`, `*SUMMARY*.md`, `*REPORT*.md` | ||
| - Phase completion files (`PHASE_*.md`) | ||
| - Test-related reports (`*TEST*.md`) | ||
| - Examples: `IMPLEMENTATION_COMPLETE.md`, `PHASE_1_COMPLETION_SUMMARY.md` | ||
|
|
||
| ### 5. Research Files → `docs/research/` | ||
| - Files matching `*RESEARCH*.md` or `*INDEX*.md` | ||
| - Examples: `RESEARCH_SUMMARY.md`, `API_TESTS_INDEX.md` | ||
|
|
||
| ### 6. Checklists → `docs/checklists/` | ||
| - Files matching `*CHECKLIST*.md` | ||
| - Examples: `IMPLEMENTATION_CHECKLIST.md`, `MIGRATION_CHECKLIST.md` | ||
|
|
||
| ## Optionality and failure behavior | ||
|
|
||
| **Project stance (required):** **Require** dependencies where they belong; **require** clear, loud failures—no silent or “graceful” degradation. | ||
|
|
||
| - **Force requirement where it belongs.** Do not make dependencies “optional” just to avoid startup or runtime failure. If a service or config is required for correctness (e.g. go-backend, temporal-host, database), treat it as required and fail when it is missing or down. | ||
| - **Fail clearly, not silently.** You **must** use explicit failures (preflight failed, runtime error)—not continuing with reduced functionality, logging-only warnings, or hiding errors. Users and operators **must** see *what* failed (e.g. named items: `go-backend; temporal-host`) and that the process did not silently degrade. | ||
| - **Graceful in other ways.** Be “graceful” only via: retries with visible feedback (e.g. “Waiting for X… (2/6)”); error messages that list each failing item (semicolon- or newline-separated, not one vague blob); actionable messages and non-obscure stack traces. Do *not* use optionality or silent fallbacks as a substitute for fixing or starting the real dependency. | ||
|
|
||
| **When working as an AI agent:** Follow this stance when adding preflight checks, startup logic, or error handling; do not suggest making required dependencies optional to “fix” failures. | ||
|
|
||
| --- | ||
|
|
||
| ## AI Agent Instructions | ||
|
|
||
| **Planner agents (no code in docs/plans):** Planner agents (PM, Analyst, Architect, SM, TEA, UX Designer, Tech Writer, BMad Master) must **never write code** in documentation or plans. Equip engineer agents or others to create code or act on docs; write specs, criteria, and handoffs—not implementation. Avoid stuffing docs or plans with code where not relevant; prefer references, file paths, or brief pseudocode when necessary. | ||
|
|
||
| **Subagent swarm (async orchestration):** If you have subagent/swarm capabilities, call task agents **async** so you are reawoken as each completes; spawn more agents or do more work then. Run a swarm: break down and isolate tasks well; **max 50 concurrent task agents at a time** (not 5). Work in between (plan, monitor); when idle you are reawoken on each completion to re-eval, spawn more, or consolidate. | ||
|
|
||
| **Subagent deployment: native CLI + thegent:** Use **both** native subagents (when present in CLI tools) and thegent subagents. **Native subagents:** Cursor Agent, Gemini CLI, Codex subagent, Copilot CLI, Claude Code—invoke these directly when the tool exposes subagent/agent capabilities (e.g. `cursor agent`, `codex-subagent`). **Thegent subagents:** `thegent run gemini`, `thegent run droid`, `thegent run cursor`, `thegent run codex`, `thegent run copilot`, `thegent run claude`—use thegent for unified orchestration, model passthrough, and droid dispatch. Prefer native when you need tool-specific behavior; use thegent for cross-provider orchestration, droids, or when model/env control is needed. See `docs/reference/THGENT_QUICK_REFERENCE.md`. | ||
|
|
||
| **Codex CLI idle/poll behavior:** When wrapping up a task, end with a long wait + poll loop to simulate idle. Poll at a predictable 30s interval, and structure it so user interruption stops only the sleep/wait (not child agents), allowing the user to steer without interrupting subagents. | ||
|
|
||
| **Phased WBS and plans with DAGs:** When generating plans, roadmaps, or implementation breakdowns, use a **phased Work Breakdown Structure (WBS)** and model **dependencies as a DAG** (directed acyclic graph). Structure work into ordered phases (e.g. Phase 1: Discovery/Scope, Phase 2: Design, Phase 3: Build, Phase 4: Test/Validate, Phase 5: Deploy/Handoff). Tasks must have explicit predecessors with no cycles; list dependencies so execution order is unambiguous. Prefer a phased WBS plus a dependency list or table: **Phase | Task ID | Description | Depends On**. Planner agents must use phased WBS and DAG-style dependencies in plans and PRDs so implementers and PMs can schedule and parallelize correctly. | ||
|
|
||
| **Agent-led environment; no user-handoff tasks:** Assume **agent-driven, agent-led** execution. User and external humans do not perform plan steps—only prompts and basic elicitation. **Never** put in plans: "Schedule external security audit", "Stakeholder Presentation", "Team Kickoff: Assign owners", "Human checkpoint", "Get approval from X", or any task that requires a human to do work. Agents produce deliverables (e.g. presentation doc, owner manifest); agents own decomposition, execution, and handoffs. **Timescales:** Use **aggressive** estimates in agent terms only (tool calls, parallel subagents, wall clock in minutes). Forbidden: "2 days", "schedule X", "assign owners". Use: "N tool calls", "~M min wall clock". See CLAUDE.md for the full timescale mapping. | ||
|
|
||
| **When working as an AI agent:** | ||
|
|
||
| - **NEVER** create `.md` files in the project root (except the allowed files above) | ||
| - **ALWAYS** place new documentation in the appropriate `docs/` subdirectory | ||
| - **VERIFY** file location before creating documentation | ||
| - **MOVE** misplaced files to correct subdirectories if found | ||
| - **REFERENCE** this structure when users ask about documentation organization | ||
| - **DO NOT** ask for permission or priority order; decide on your own, run needed commands, and proceed with the most critical path. | ||
|
|
||
| **Native services over Docker; local OSS/free only:** Prefer **native** service runs (e.g. `make install-native`, process-compose) over Docker for dev. Use Docker only when native is not feasible. **Strictly prefer local, OSS, and free**—do not recommend paid online services when local or free alternatives exist; prefer self-hosted, open-source, or free-tier options. | ||
|
|
||
| **See also:** For context management, delegation table, dev environment, and package manager instructions see `CLAUDE.md` (or `claude.md`). For IDE-specific agent activation see `.bmad/docs/` (e.g. `claude-code-instructions.md`, `gemini-instructions.md`, `cursor-instructions.md`). | ||
|
|
||
| ## Maintenance | ||
|
|
||
| - Use the `organize_docs.sh` script to reorganize misplaced files | ||
| - Keep root directory clean and organized | ||
| - Review and reorganize quarterly to maintain structure | ||
| - Update this governance document as the project evolves | ||
|
|
||
|
|
||
| ## Multi-Actor Coordination | ||
| - **Command Debouncing**: High-impact commands (`make lint`, `make test`, `make quality`, `make validate`) MUST use `smart-command.sh` (via Makefile/Taskfile) to prevent conflicts between multiple root/subagents. | ||
| - **Shared Service Awareness**: `process-compose` is the primary orchestrator. Use its CLI/API (e.g., `make dev-status`, `make dev-restart`) instead of raw scripts to ensure global visibility. | ||
| - **Graceful Service Interaction**: Infrastructure and app services use "if-not-running" wrappers to allow multiple actors to share a single set of healthy processes. DO NOT force-kill shared resources. | ||
| - **Lock Files**: Active command locks are stored in `.process-compose/locks/`. Always check for existing locks before running heavy tasks. | ||
| - **Unified Logging**: Read aggregated logs from `.process-compose/process-compose.log`. | ||
|
|
||
| ## Opinionated Quality Enforcement | ||
| - We want opinionated rules that enforce opinionated styling to a strict degree. | ||
| - This is an exclusively agent/vibecoded project; programmatic enforcement must guard against bad quality and antipatterns. | ||
| - Rather than disables or ignores, fix code properly. | ||
|
|
||
| ## Lint Violation Governance | ||
|
|
||
| **Before filing bugs or writing code for lint violations:** | ||
|
|
||
| 1. **Verify true violations**: Check if flagged issues are truly unused, unimplemented, or can be refactored without losing functionality | ||
| 2. **Never use ignorers**: Never add `//nolint:lintname`, `//lint-ignore`, or skip linter configurations to silence violations | ||
| 3. **Fix properly**: Address root causes—extract functions, constants, reduce complexity, not suppression | ||
| 4. **Test coverage preserved**: Ensure all fixes maintain existing test coverage; do not disable tests to pass linters | ||
|
|
||
| **Violation handling priorities:** | ||
|
|
||
| | Category | Action | | ||
| |----------|--------| | ||
| | `revive` (unused params in mocks) | Rename to `_paramName` if intentionally unused | | ||
| | `goconst` (repeated strings) | Extract to named constants | | ||
| | `mnd` (magic numbers) | Extract to named constants with units | | ||
| | `gocognit` (complexity) | Extract helper functions, reduce nesting | | ||
| | `funlen` (long functions) | Split into focused helper functions | | ||
| | `gochecknoglobals` | Validate necessity; convert to singletons if needed | | ||
| | `gosec` (security) | Fix immediately; no exceptions | | ||
|
|
||
| **Subagent delegation for lint fixes:** | ||
| - Group 1-3 related files per subagent by violation type | ||
| - Production code takes priority over test code for complexity/security | ||
| - Test code refactoring (funlen) can be delegated more aggressively | ||
|
|
||
| ## Child-Agent and Delegation Policy | ||
| - Use child agents liberally for scoped discovery, audits, multi-repo scans, and implementation planning before direct parent-agent edits. | ||
| - Prefer delegating high-context or high-churn tasks to subagents, and keep parent-agent changes focused on integration and finalization. | ||
| - Reserve parent-agent direct writes for the narrowest, final decision layer. | ||
| ## References | ||
| - Parent workspace: /Users/kooshapari/CodeProjects/Phenotype/repos/CLAUDE.md |
There was a problem hiding this comment.
🟠 Architect Review — HIGH
The new agent instructions hardcode local absolute filesystem paths (/Users/kooshapari/...) for AgilePlus and the parent workspace, assuming all environments share the same machine layout; in normal cloned environments these paths will not exist, making the referenced governance docs effectively unreachable.
Suggestion: Replace these machine-specific absolute paths with repository-relative links or stable URLs and, if cross-repo references are required, document a portable lookup convention that works in CI and for all contributors.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** AGENTS.md
**Line:** 10:13
**Comment:**
*HIGH: The new agent instructions hardcode local absolute filesystem paths (/Users/kooshapari/...) for AgilePlus and the parent workspace, assuming all environments share the same machine layout; in normal cloned environments these paths will not exist, making the referenced governance docs effectively unreachable.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished reviewing your PR. |
|
CodeAnt AI is running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
size:S
Sequence DiagramThis PR simplifies in-repo agent instructions to reference AgilePlus tracking and a shared workspace guide, and adds GitHub funding settings so the project exposes sponsor options. sequenceDiagram
participant Agent
participant Repo
participant AgilePlus
participant WorkspaceGuide
participant GitHubUser
participant GitHub
participant SponsorPage
Agent->>Repo: Open AGENTS instructions
Repo-->>Agent: Show project overview and AgilePlus mandate
Agent->>AgilePlus: Track new work item
Agent->>WorkspaceGuide: Read parent workspace instructions
GitHubUser->>GitHub: View project page
GitHub->>Repo: Read funding configuration
GitHub-->>GitHubUser: Display sponsor options
GitHubUser->>SponsorPage: Open sponsor link
Generated by CodeAnt AI |
Comment on lines
+10
to
+13
| Reference: /Users/kooshapari/CodeProjects/Phenotype/repos/AgilePlus | ||
|
|
||
| Only these files should remain in the project root: | ||
| - `README.md` - Main project documentation | ||
| - `CHANGELOG.md` - Project changelog | ||
| - `AGENTS.md` - This governance file (AI agent instructions) | ||
| - `CLAUDE.md` / `claude.md` - Claude-specific instructions | ||
| - `00_START_HERE.md` - Getting started guide (if applicable) | ||
|
|
||
| ## Documentation Structure | ||
|
|
||
| All other `.md` files must be organized in `docs/` subdirectories: | ||
|
|
||
| ``` | ||
| docs/ | ||
| ├── guides/ # Implementation guides and how-tos | ||
| │ └── quick-start/ # Quick start guides | ||
| ├── reports/ # Completion reports, summaries, status reports | ||
| ├── research/ # Research summaries, indexes, analysis | ||
| ├── reference/ # Quick references, API references | ||
| └── checklists/ # Implementation checklists, verification lists | ||
| ``` | ||
|
|
||
| ## File Organization Rules | ||
|
|
||
| **When creating or moving documentation:** | ||
|
|
||
| ### 1. Quick Starts → `docs/guides/quick-start/` | ||
| - Files matching `*QUICK_START*.md` or `*QUICKSTART*.md` | ||
| - Examples: `GRAPH_OPTIMIZATION_QUICK_START.md`, `AUTH_ROUTES_QUICK_START.md` | ||
|
|
||
| ### 2. Quick References → `docs/reference/` | ||
| - Files matching `*QUICK_REFERENCE*.md` or `*QUICK_REF*.md` | ||
| - Examples: `NATS_QUICK_REFERENCE.md`, `CLI_QUICK_REFERENCE.md` | ||
|
|
||
| ### 3. Implementation Guides → `docs/guides/` | ||
| - Files matching `*IMPLEMENTATION_GUIDE*.md` or `*GUIDE*.md` | ||
| - General implementation documentation | ||
| - Examples: `API_IMPLEMENTATION_GUIDE.md`, `DEPLOYMENT_GUIDE.md` | ||
|
|
||
| ### 4. Completion Reports → `docs/reports/` | ||
| - Files matching `*COMPLETE*.md`, `*COMPLETION*.md`, `*SUMMARY*.md`, `*REPORT*.md` | ||
| - Phase completion files (`PHASE_*.md`) | ||
| - Test-related reports (`*TEST*.md`) | ||
| - Examples: `IMPLEMENTATION_COMPLETE.md`, `PHASE_1_COMPLETION_SUMMARY.md` | ||
|
|
||
| ### 5. Research Files → `docs/research/` | ||
| - Files matching `*RESEARCH*.md` or `*INDEX*.md` | ||
| - Examples: `RESEARCH_SUMMARY.md`, `API_TESTS_INDEX.md` | ||
|
|
||
| ### 6. Checklists → `docs/checklists/` | ||
| - Files matching `*CHECKLIST*.md` | ||
| - Examples: `IMPLEMENTATION_CHECKLIST.md`, `MIGRATION_CHECKLIST.md` | ||
|
|
||
| ## Optionality and failure behavior | ||
|
|
||
| **Project stance (required):** **Require** dependencies where they belong; **require** clear, loud failures—no silent or “graceful” degradation. | ||
|
|
||
| - **Force requirement where it belongs.** Do not make dependencies “optional” just to avoid startup or runtime failure. If a service or config is required for correctness (e.g. go-backend, temporal-host, database), treat it as required and fail when it is missing or down. | ||
| - **Fail clearly, not silently.** You **must** use explicit failures (preflight failed, runtime error)—not continuing with reduced functionality, logging-only warnings, or hiding errors. Users and operators **must** see *what* failed (e.g. named items: `go-backend; temporal-host`) and that the process did not silently degrade. | ||
| - **Graceful in other ways.** Be “graceful” only via: retries with visible feedback (e.g. “Waiting for X… (2/6)”); error messages that list each failing item (semicolon- or newline-separated, not one vague blob); actionable messages and non-obscure stack traces. Do *not* use optionality or silent fallbacks as a substitute for fixing or starting the real dependency. | ||
|
|
||
| **When working as an AI agent:** Follow this stance when adding preflight checks, startup logic, or error handling; do not suggest making required dependencies optional to “fix” failures. | ||
|
|
||
| --- | ||
|
|
||
| ## AI Agent Instructions | ||
|
|
||
| **Planner agents (no code in docs/plans):** Planner agents (PM, Analyst, Architect, SM, TEA, UX Designer, Tech Writer, BMad Master) must **never write code** in documentation or plans. Equip engineer agents or others to create code or act on docs; write specs, criteria, and handoffs—not implementation. Avoid stuffing docs or plans with code where not relevant; prefer references, file paths, or brief pseudocode when necessary. | ||
|
|
||
| **Subagent swarm (async orchestration):** If you have subagent/swarm capabilities, call task agents **async** so you are reawoken as each completes; spawn more agents or do more work then. Run a swarm: break down and isolate tasks well; **max 50 concurrent task agents at a time** (not 5). Work in between (plan, monitor); when idle you are reawoken on each completion to re-eval, spawn more, or consolidate. | ||
|
|
||
| **Subagent deployment: native CLI + thegent:** Use **both** native subagents (when present in CLI tools) and thegent subagents. **Native subagents:** Cursor Agent, Gemini CLI, Codex subagent, Copilot CLI, Claude Code—invoke these directly when the tool exposes subagent/agent capabilities (e.g. `cursor agent`, `codex-subagent`). **Thegent subagents:** `thegent run gemini`, `thegent run droid`, `thegent run cursor`, `thegent run codex`, `thegent run copilot`, `thegent run claude`—use thegent for unified orchestration, model passthrough, and droid dispatch. Prefer native when you need tool-specific behavior; use thegent for cross-provider orchestration, droids, or when model/env control is needed. See `docs/reference/THGENT_QUICK_REFERENCE.md`. | ||
|
|
||
| **Codex CLI idle/poll behavior:** When wrapping up a task, end with a long wait + poll loop to simulate idle. Poll at a predictable 30s interval, and structure it so user interruption stops only the sleep/wait (not child agents), allowing the user to steer without interrupting subagents. | ||
|
|
||
| **Phased WBS and plans with DAGs:** When generating plans, roadmaps, or implementation breakdowns, use a **phased Work Breakdown Structure (WBS)** and model **dependencies as a DAG** (directed acyclic graph). Structure work into ordered phases (e.g. Phase 1: Discovery/Scope, Phase 2: Design, Phase 3: Build, Phase 4: Test/Validate, Phase 5: Deploy/Handoff). Tasks must have explicit predecessors with no cycles; list dependencies so execution order is unambiguous. Prefer a phased WBS plus a dependency list or table: **Phase | Task ID | Description | Depends On**. Planner agents must use phased WBS and DAG-style dependencies in plans and PRDs so implementers and PMs can schedule and parallelize correctly. | ||
|
|
||
| **Agent-led environment; no user-handoff tasks:** Assume **agent-driven, agent-led** execution. User and external humans do not perform plan steps—only prompts and basic elicitation. **Never** put in plans: "Schedule external security audit", "Stakeholder Presentation", "Team Kickoff: Assign owners", "Human checkpoint", "Get approval from X", or any task that requires a human to do work. Agents produce deliverables (e.g. presentation doc, owner manifest); agents own decomposition, execution, and handoffs. **Timescales:** Use **aggressive** estimates in agent terms only (tool calls, parallel subagents, wall clock in minutes). Forbidden: "2 days", "schedule X", "assign owners". Use: "N tool calls", "~M min wall clock". See CLAUDE.md for the full timescale mapping. | ||
|
|
||
| **When working as an AI agent:** | ||
|
|
||
| - **NEVER** create `.md` files in the project root (except the allowed files above) | ||
| - **ALWAYS** place new documentation in the appropriate `docs/` subdirectory | ||
| - **VERIFY** file location before creating documentation | ||
| - **MOVE** misplaced files to correct subdirectories if found | ||
| - **REFERENCE** this structure when users ask about documentation organization | ||
| - **DO NOT** ask for permission or priority order; decide on your own, run needed commands, and proceed with the most critical path. | ||
|
|
||
| **Native services over Docker; local OSS/free only:** Prefer **native** service runs (e.g. `make install-native`, process-compose) over Docker for dev. Use Docker only when native is not feasible. **Strictly prefer local, OSS, and free**—do not recommend paid online services when local or free alternatives exist; prefer self-hosted, open-source, or free-tier options. | ||
|
|
||
| **See also:** For context management, delegation table, dev environment, and package manager instructions see `CLAUDE.md` (or `claude.md`). For IDE-specific agent activation see `.bmad/docs/` (e.g. `claude-code-instructions.md`, `gemini-instructions.md`, `cursor-instructions.md`). | ||
|
|
||
| ## Maintenance | ||
|
|
||
| - Use the `organize_docs.sh` script to reorganize misplaced files | ||
| - Keep root directory clean and organized | ||
| - Review and reorganize quarterly to maintain structure | ||
| - Update this governance document as the project evolves | ||
|
|
||
|
|
||
| ## Multi-Actor Coordination | ||
| - **Command Debouncing**: High-impact commands (`make lint`, `make test`, `make quality`, `make validate`) MUST use `smart-command.sh` (via Makefile/Taskfile) to prevent conflicts between multiple root/subagents. | ||
| - **Shared Service Awareness**: `process-compose` is the primary orchestrator. Use its CLI/API (e.g., `make dev-status`, `make dev-restart`) instead of raw scripts to ensure global visibility. | ||
| - **Graceful Service Interaction**: Infrastructure and app services use "if-not-running" wrappers to allow multiple actors to share a single set of healthy processes. DO NOT force-kill shared resources. | ||
| - **Lock Files**: Active command locks are stored in `.process-compose/locks/`. Always check for existing locks before running heavy tasks. | ||
| - **Unified Logging**: Read aggregated logs from `.process-compose/process-compose.log`. | ||
|
|
||
| ## Opinionated Quality Enforcement | ||
| - We want opinionated rules that enforce opinionated styling to a strict degree. | ||
| - This is an exclusively agent/vibecoded project; programmatic enforcement must guard against bad quality and antipatterns. | ||
| - Rather than disables or ignores, fix code properly. | ||
|
|
||
| ## Lint Violation Governance | ||
|
|
||
| **Before filing bugs or writing code for lint violations:** | ||
|
|
||
| 1. **Verify true violations**: Check if flagged issues are truly unused, unimplemented, or can be refactored without losing functionality | ||
| 2. **Never use ignorers**: Never add `//nolint:lintname`, `//lint-ignore`, or skip linter configurations to silence violations | ||
| 3. **Fix properly**: Address root causes—extract functions, constants, reduce complexity, not suppression | ||
| 4. **Test coverage preserved**: Ensure all fixes maintain existing test coverage; do not disable tests to pass linters | ||
|
|
||
| **Violation handling priorities:** | ||
|
|
||
| | Category | Action | | ||
| |----------|--------| | ||
| | `revive` (unused params in mocks) | Rename to `_paramName` if intentionally unused | | ||
| | `goconst` (repeated strings) | Extract to named constants | | ||
| | `mnd` (magic numbers) | Extract to named constants with units | | ||
| | `gocognit` (complexity) | Extract helper functions, reduce nesting | | ||
| | `funlen` (long functions) | Split into focused helper functions | | ||
| | `gochecknoglobals` | Validate necessity; convert to singletons if needed | | ||
| | `gosec` (security) | Fix immediately; no exceptions | | ||
|
|
||
| **Subagent delegation for lint fixes:** | ||
| - Group 1-3 related files per subagent by violation type | ||
| - Production code takes priority over test code for complexity/security | ||
| - Test code refactoring (funlen) can be delegated more aggressively | ||
|
|
||
| ## Child-Agent and Delegation Policy | ||
| - Use child agents liberally for scoped discovery, audits, multi-repo scans, and implementation planning before direct parent-agent edits. | ||
| - Prefer delegating high-context or high-churn tasks to subagents, and keep parent-agent changes focused on integration and finalization. | ||
| - Reserve parent-agent direct writes for the narrowest, final decision layer. | ||
| ## References | ||
| - Parent workspace: /Users/kooshapari/CodeProjects/Phenotype/repos/CLAUDE.md |
There was a problem hiding this comment.
🟠 Architect Review — HIGH
Agent guidance in AGENTS.md points to machine-specific absolute filesystem paths (/Users/kooshapari/...) for AgilePlus and the parent CLAUDE workspace, so contributors and CI/agent runtimes in other environments cannot resolve or follow the referenced instructions.
Suggestion: Replace the absolute local paths with repository-relative paths or accessible URLs, and ensure there is a repo-local or otherwise portable reference that agents can use regardless of the host filesystem layout.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** AGENTS.md
**Line:** 10:13
**Comment:**
*HIGH: Agent guidance in AGENTS.md points to machine-specific absolute filesystem paths (/Users/kooshapari/...) for AgilePlus and the parent CLAUDE workspace, so contributors and CI/agent runtimes in other environments cannot resolve or follow the referenced instructions.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
CodeAnt AI is running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
size:S
Sequence DiagramThis PR simplifies how agents get project guidance and adds repository funding settings so GitHub can display sponsorship options. The diagram shows how contributors and agents now interact with the repo docs, AgilePlus tracking, and sponsorship links. sequenceDiagram
participant Contributor
participant AI_Agent as AI Agent
participant GitHub
participant Repo
participant AgilePlus
participant ParentWorkspace as Parent workspace docs
participant SponsorPage as Sponsor page
Contributor->>GitHub: View repository page
GitHub-->>Contributor: Show sponsor options from funding config
Contributor->>SponsorPage: Open sponsor page link
AI_Agent->>Repo: Read AGENTS instructions
Repo-->>AI_Agent: Return project overview and AgilePlus mandate
AI_Agent->>AgilePlus: Track work in AgilePlus
AI_Agent->>ParentWorkspace: Read parent workspace guidance
Generated by CodeAnt AI |
Comment on lines
+1
to
+2
| github: [KooshaPari] | ||
| custom: ["https://kooshapari.com/sponsor"] |
There was a problem hiding this comment.
🟠 Architect Review — HIGH
Root-level FUNDING.yml adds a custom sponsor URL, but this repo already has .github/FUNDING.yml (the file GitHub actually reads), so the new custom link will not be applied and the sponsorship configuration change is effectively ignored.
Suggestion: Consolidate sponsorship settings into .github/FUNDING.yml (including the custom URL) and remove the unused root-level FUNDING.yml so GitHub renders the intended sponsor links from a single source of truth.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** FUNDING.yml
**Line:** 1:2
**Comment:**
*HIGH: Root-level FUNDING.yml adds a custom sponsor URL, but this repo already has `.github/FUNDING.yml` (the file GitHub actually reads), so the new `custom` link will not be applied and the sponsorship configuration change is effectively ignored.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
CodeAnt AI is running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
size:S
Sequence DiagramThis PR configures GitHub sponsorship metadata and replaces a detailed governance document with a concise agent instructions file that points to project and workspace references. sequenceDiagram
participant Viewer
participant GitHub
participant Repo
participant SponsorPage
participant Agent
Viewer->>GitHub: Open repository page
GitHub->>Repo: Read funding configuration
Repo-->>GitHub: Return sponsor settings
GitHub-->>Viewer: Display sponsor options
Viewer->>SponsorPage: Follow sponsor link
Agent->>Repo: Open AGENTS instructions
Repo-->>Agent: Return project overview and references
Generated by CodeAnt AI |
|
CodeAnt AI finished running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
CodeAnt AI is running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
size:S
Sequence DiagramThis PR enables GitHub sponsorship options for the project and simplifies the root agent instructions to reference AgilePlus tracking and shared workspace guidance. sequenceDiagram
participant Contributor
participant GitHub
participant Sponsor
participant Agent
participant AGENTS
participant AgilePlus
participant ParentWorkspaceDocs
Contributor->>GitHub: Commit funding and agent files
GitHub->>GitHub: Load funding configuration
GitHub-->>Sponsor: Display sponsor options
Sponsor->>GitHub: Select sponsor project
GitHub-->>Sponsor: Open sponsor page
Agent->>AGENTS: Read project instructions
AGENTS-->>Agent: Provide AgilePlus mandate and workspace link
Agent->>AgilePlus: Track work item
Agent->>ParentWorkspaceDocs: Follow workspace guidance
Generated by CodeAnt AI |
|
CodeAnt AI finished running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
CodeAnt AI is running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
size:S
Sequence DiagramThis PR replaces the detailed root agent governance document with a concise overview that points agents to AgilePlus tracking and parent workspace guidance, and adds funding configuration so GitHub can surface sponsorship options for the project. sequenceDiagram
participant Agent
participant Repo
participant AgilePlus
participant ParentWorkspace
participant GitHubUser
participant GitHub
Agent->>Repo: Open AGENTS instructions
Repo-->>Agent: Return overview and references
Agent->>AgilePlus: Find tracked work item
Agent->>ParentWorkspace: Read workspace guidance
GitHubUser->>GitHub: View repository page
GitHub->>Repo: Load funding configuration
Repo-->>GitHub: Sponsor settings
GitHub-->>GitHubUser: Show sponsor options
Generated by CodeAnt AI |
Comment on lines
+1
to
+2
| github: [KooshaPari] | ||
| custom: ["https://kooshapari.com/sponsor"] |
There was a problem hiding this comment.
🟠 Architect Review — HIGH
Sponsorship configuration was added to a root-level FUNDING.yml, but GitHub only reads .github/FUNDING.yml; as a result, the new custom sponsor URL is ignored and not shown in the GitHub Sponsors UI.
Suggestion: Move/merge the custom sponsor URL (and any desired github entries) into .github/FUNDING.yml and remove the root-level FUNDING.yml so GitHub uses the intended configuration.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** FUNDING.yml
**Line:** 1:2
**Comment:**
*HIGH: Sponsorship configuration was added to a root-level FUNDING.yml, but GitHub only reads .github/FUNDING.yml; as a result, the new custom sponsor URL is ignored and not shown in the GitHub Sponsors UI.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
CodeAnt AI is running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
size:S
Sequence DiagramThis PR enables GitHub sponsorship visibility for the repository and simplifies root agent instructions to reference AgilePlus tracking and the parent workspace guide. sequenceDiagram
participant Contributor
participant GitHub
participant Sponsor
participant Agent
participant ParentWorkspace
Contributor->>GitHub: Open repository page
GitHub->>GitHub: Load funding settings from funding config
GitHub-->>Contributor: Show sponsor options and custom sponsor link
Contributor->>Sponsor: Choose sponsorship option
Agent->>Agent: Read simplified agent instructions
Agent->>ParentWorkspace: Follow parent workspace guide reference
Agent-->>Agent: Apply AgilePlus tracking requirement for work
Generated by CodeAnt AI |
Comment on lines
+1
to
+2
| github: [KooshaPari] | ||
| custom: ["https://kooshapari.com/sponsor"] |
There was a problem hiding this comment.
🟠 Architect Review — HIGH
FUNDING.yml is added at the repository root, but GitHub only reads funding configuration from .github/FUNDING.yml, so these github and custom sponsor settings will be ignored and the sponsor button will not reflect them.
Suggestion: Move this configuration into .github/FUNDING.yml (creating that file if needed) so GitHub picks up the github and custom entries instead of an unused root-level funding file.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** FUNDING.yml
**Line:** 1:2
**Comment:**
*HIGH: FUNDING.yml is added at the repository root, but GitHub only reads funding configuration from `.github/FUNDING.yml`, so these `github` and `custom` sponsor settings will be ignored and the sponsor button will not reflect them.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished running the review. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
Governance bootstrap
Note
Low Risk
Changes are limited to repository metadata/docs (sponsorship config and agent instructions) with no impact to runtime code paths.
Overview
Simplifies
AGENTS.mdfrom a detailed documentation-governance/agent-policy document into a short set of project/mandate references (Project Overview, AgilePlus tracking requirement, and a pointer to the parent workspace instructions).Adds
FUNDING.ymlto configure GitHub Sponsors and a custom sponsorship URL.Reviewed by Cursor Bugbot for commit d01308b. Bugbot is set up for automated code reviews on this repo. Configure here.
CodeAnt-AI Description
Add GitHub sponsorship details and simplify root agent instructions
What Changed
Impact
✅ Project sponsorship is visible on GitHub✅ Shorter root instructions for agents✅ Less policy text in the repository root🔄 Retrigger CodeAnt AI Review
Details
💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.