Skip to content

Commit 64508e4

Browse files
gracefullightgracefullight
committed
docs: generate AGENTS.md files across the repository to provide context
1 parent 045a73c commit 64508e4

93 files changed

Lines changed: 3032 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agent/workflows/deepinit.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
description: Create comprehensive, hierarchical AGENTS.md documentation across the codebase
3+
---
4+
5+
# MANDATORY RULES — VIOLATION IS FORBIDDEN
6+
7+
- **Response language follows `language` setting in `.agent/config/user-preferences.yaml` if configured.**
8+
- **NEVER skip steps.** Execute from Step 0 in order. Explicitly report completion of each step before proceeding.
9+
- **You MUST use MCP tools throughout the entire workflow.** This is NOT optional.
10+
- Use code analysis tools (`get_symbols_overview`, `find_symbol`, `search_for_pattern`, `list_dir`, `view_file`) for code exploration.
11+
- Use file writing tools to generate `AGENTS.md` files.
12+
- **Exclude directories:** Respect the project's `.gitignore` as the source of truth for excluding directories (e.g., `node_modules`, `dist`, `build`, etc.). Additionally, exclude framework auto-generated or native shell directories that do not contain core business logic (e.g., Flutter's `android`, `ios`, `macos`, `linux`, `windows`, `web`). Do not generate `AGENTS.md` for these ignored or excluded paths.
13+
14+
---
15+
16+
## Step 0: Preparation
17+
18+
1. Read `.agent/skills/workflow-guide/SKILL.md` and confirm Core Rules.
19+
20+
---
21+
22+
## Step 1: Map Directory Structure
23+
24+
**Identify all valid directories recursively.**
25+
26+
- **Target Level 0:** `/` (root)
27+
- **Target Levels:** Drill down iteratively (e.g., Level 1: `/src`, `/docs`, `/tests`, `/apps`, `/packages`; Level 2: nested structure).
28+
- **Empty Directory Handling:**
29+
- If no files and no subdirectories: **Skip**.
30+
- If only config files or generated files: minimal `AGENTS.md`.
31+
32+
---
33+
34+
## Step 2: Create Work Plan
35+
36+
Determine generation order.
37+
**IMPORTANT:** Generation MUST happen top-down (parent first) to ensure parent tags are correct.
38+
39+
Plan the work across directory levels. Report the depth plan to the user.
40+
41+
---
42+
43+
## Step 3: Content Generation Level by Level
44+
45+
For each directory in the plan:
46+
47+
1. **Read all directory content** using `list_dir` and analyze the purpose using `get_symbols_overview` or reading key files.
48+
2. **Determine Parent Reference:**
49+
- Root has no parent tag.
50+
- Any child has: `<!-- Parent: {relative_path_to_parent}/AGENTS.md -->`.
51+
3. **Template Format to Use:**
52+
53+
```markdown
54+
<!-- Parent: ../AGENTS.md --> <!-- Adjust this relative path appropriately. Omit entirely for root directory. -->
55+
<!-- Generated: {timestamp} | Updated: {timestamp} -->
56+
57+
# {Directory Name}
58+
59+
## Purpose
60+
{One-paragraph description of what this directory contains and its role}
61+
62+
## Key Files
63+
| File | Description |
64+
|------|-------------|
65+
| `file.ts` | Detailed one-line purpose |
66+
67+
## Subdirectories
68+
| Directory | Purpose |
69+
|-----------|---------|
70+
| `subdir/` | What it contains (see `subdir/AGENTS.md`) |
71+
72+
## For AI Agents
73+
### Working In This Directory
74+
{Special instructions for AI agents modifying files here}
75+
76+
### Dependencies
77+
{Internal or external parts of the codebase this depends on}
78+
79+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
80+
```
81+
82+
1. **Parallel Generation:**
83+
- If directories are large or complex, use `oh-my-ag agent:spawn {agent_id} "Write AGENTS.md based on this directory" session_id -w {path}` to distribute the context load across suitable domain agents.
84+
- For simple directories, you can write them directly.
85+
86+
---
87+
88+
## Step 4: Compare and Update Existing (If Applicable)
89+
90+
If an `AGENTS.md` file already exists:
91+
92+
1. Parse the existing file.
93+
2. Compare structural changes (new files, removed subdirectories).
94+
3. **CRITICAL:** Preserve the manual annotation block intact. Everything after `<!-- MANUAL:` must be copied exactly.
95+
4. Merge contents and update the generated timestamp.
96+
97+
---
98+
99+
## Step 5: Validate Hierarchy
100+
101+
Use tools to perform a sweeping check on all generated `AGENTS.md` files:
102+
103+
1. Ensure all `<!-- Parent: -->` references resolve to an existing `AGENTS.md` file.
104+
2. Verify all listed `Key Files` exist in the directory.
105+
3. Remove orphaned `AGENTS.md` files where directories no longer exist or parent links are broken.

‎AGENTS.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<!-- Generated: 2026-03-02T14:39:02+11:00 | Updated: 2026-03-02T14:39:02+11:00 -->
2+
3+
# juny (Project Root)
4+
5+
## Purpose
6+
7+
Top-level root directory of the Fullstack Monorepo built with FastAPI (Backend), Flutter (Mobile), and GCP (Infrastructure). Contains all applications, packages, common configuration files, and workflows.
8+
9+
## Key Files
10+
11+
| File | Description |
12+
|------|-------------|
13+
| `mise.toml` | Main configurations (Runtime versions, task runner, etc.) |
14+
| `biome.json` | Biome configuration file for JavaScript/TypeScript (linting and formatting) |
15+
| `commitlint.config.cjs` | commitlint configuration for checking commit message rules |
16+
| `README.md` | Project overview and guide documentation |
17+
18+
## Subdirectories
19+
20+
| Directory | Purpose |
21+
|-----------|---------|
22+
| `apps/` | Directory containing core application code such as backend, frontend, mobile, and infrastructure (see `apps/AGENTS.md`) |
23+
| `packages/` | Directory for reusable shared modules like design tokens and i18n (see `packages/AGENTS.md`) |
24+
| `.github/` | CI/CD pipeline (GitHub Actions) and Github configurations |
25+
| `.agent/` | Configurations for AI agents' rules and workflows (skills, workflows) |
26+
27+
## For AI Agents
28+
29+
### Working In This Directory
30+
31+
Take caution when working in this directory as global configurations can significantly impact applications and packages across the entire project. Only access this to modify global project linting rules, commit rules, or global scripts.
32+
33+
### Dependencies
34+
35+
None.
36+
37+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<!-- Parent: ../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:39:02+11:00 | Updated: 2026-03-02T14:39:02+11:00 -->
3+
4+
# apps
5+
6+
## Purpose
7+
8+
Directory containing the main applications that make up the project. It is separated by roles such as backend platform, Background Worker, mobile app client, and IaC (infrastructure) code for deployment.
9+
10+
## Key Files
11+
12+
| File | Description |
13+
|------|-------------|
14+
| - | No separate main configuration files; used to maintain the structure of subdirectories. |
15+
16+
## Subdirectories
17+
18+
| Directory | Purpose |
19+
|-----------|---------|
20+
| `api/` | FastAPI-based backend service (see `api/AGENTS.md`) |
21+
| `worker/` | FastAPI-based asynchronous background worker (see `worker/AGENTS.md`) |
22+
| `mobile/` | Flutter-based cross-platform mobile client (see `mobile/AGENTS.md`) |
23+
| `infra/` | Terraform-based GCP environment infrastructure (see `infra/AGENTS.md`) |
24+
| `web/` | Web frontend environment application (see `web/AGENTS.md`) |
25+
26+
## For AI Agents
27+
28+
### Working In This Directory
29+
30+
Wrapper folder for simply managing submodule apps. Maintain an appropriate name and structure when adding or modifying new sub-apps inside the apps directory.
31+
32+
### Dependencies
33+
34+
Depends on global configurations like `mise.toml` in the root space.
35+
36+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/api/AGENTS.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<!-- Parent: ../../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:47:05+11:00 | Updated: 2026-03-02T14:47:05+11:00 -->
3+
4+
# api
5+
6+
## Purpose
7+
api Basic components of the system (auto-generated)
8+
9+
## Key Files
10+
| File | Description |
11+
|------|-------------|
12+
| `uv.lock` | Refer to feature details |
13+
| `alembic.ini` | Refer to feature details |
14+
| `Dockerfile` | Refer to feature details |
15+
| `pyproject.toml` | Refer to feature details |
16+
| `mise.toml` | Refer to feature details |
17+
| `docker-compose.infra.yml` | Refer to feature details |
18+
| `.gitignore` | Refer to feature details |
19+
| `ruff.toml` | Refer to feature details |
20+
| `.env.example` | Refer to feature details |
21+
| `openapi.json` | Refer to feature details |
22+
23+
## Subdirectories
24+
| Directory | Purpose |
25+
|-----------|---------|
26+
| `.pytest_cache/` | Submodule (see `.pytest_cache/AGENTS.md`) |
27+
| `tests/` | Submodule (see `tests/AGENTS.md`) |
28+
| `scripts/` | Submodule (see `scripts/AGENTS.md`) |
29+
| `alembic/` | Submodule (see `alembic/AGENTS.md`) |
30+
| `src/` | Submodule (see `src/AGENTS.md`) |
31+
32+
## For AI Agents
33+
### Working In This Directory
34+
Auto-scanned directory. Navigate inside for detailed structure if needed.
35+
36+
### Dependencies
37+
Based on global project settings.
38+
39+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/api/alembic/AGENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- Parent: ../../../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:47:05+11:00 | Updated: 2026-03-02T14:47:05+11:00 -->
3+
4+
# alembic
5+
6+
## Purpose
7+
alembic Basic components of the system (auto-generated)
8+
9+
## Key Files
10+
| File | Description |
11+
|------|-------------|
12+
| `script.py.mako` | Refer to feature details |
13+
| `env.py` | Refer to feature details |
14+
15+
## Subdirectories
16+
| Directory | Purpose |
17+
|-----------|---------|
18+
| `versions/` | Submodule (see `versions/AGENTS.md`) |
19+
20+
## For AI Agents
21+
### Working In This Directory
22+
Auto-scanned directory. Navigate inside for detailed structure if needed.
23+
24+
### Dependencies
25+
Based on global project settings.
26+
27+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/api/alembic/versions/AGENTS.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!-- Parent: ../../../../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:47:05+11:00 | Updated: 2026-03-02T14:47:05+11:00 -->
3+
4+
# versions
5+
6+
## Purpose
7+
versions Basic components of the system (auto-generated)
8+
9+
## Key Files
10+
| File | Description |
11+
|------|-------------|
12+
| `0001_initial.py` | Refer to feature details |
13+
14+
## Subdirectories
15+
| Directory | Purpose |
16+
|-----------|---------|
17+
| - | No submodules |
18+
19+
## For AI Agents
20+
### Working In This Directory
21+
Auto-scanned directory. Navigate inside for detailed structure if needed.
22+
23+
### Dependencies
24+
Based on global project settings.
25+
26+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/api/scripts/AGENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- Parent: ../../../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:47:05+11:00 | Updated: 2026-03-02T14:47:05+11:00 -->
3+
4+
# scripts
5+
6+
## Purpose
7+
scripts Basic components of the system (auto-generated)
8+
9+
## Key Files
10+
| File | Description |
11+
|------|-------------|
12+
| `gen_openapi.py` | Refer to feature details |
13+
| `seed.py` | Refer to feature details |
14+
15+
## Subdirectories
16+
| Directory | Purpose |
17+
|-----------|---------|
18+
| - | No submodules |
19+
20+
## For AI Agents
21+
### Working In This Directory
22+
Auto-scanned directory. Navigate inside for detailed structure if needed.
23+
24+
### Dependencies
25+
Based on global project settings.
26+
27+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/api/src/AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<!-- Parent: ../../../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:47:05+11:00 | Updated: 2026-03-02T14:47:05+11:00 -->
3+
4+
# src
5+
6+
## Purpose
7+
src Basic components of the system (auto-generated)
8+
9+
## Key Files
10+
| File | Description |
11+
|------|-------------|
12+
| `__init__.py` | Refer to feature details |
13+
| `main.py` | Refer to feature details |
14+
15+
## Subdirectories
16+
| Directory | Purpose |
17+
|-----------|---------|
18+
| `routers/` | Submodule (see `routers/AGENTS.md`) |
19+
| `medications/` | Submodule (see `medications/AGENTS.md`) |
20+
| `relations/` | Submodule (see `relations/AGENTS.md`) |
21+
| `wellness/` | Submodule (see `wellness/AGENTS.md`) |
22+
| `auth/` | Submodule (see `auth/AGENTS.md`) |
23+
| `admin/` | Submodule (see `admin/AGENTS.md`) |
24+
| `navigation/` | Submodule (see `navigation/AGENTS.md`) |
25+
| `common/` | Submodule (see `common/AGENTS.md`) |
26+
| `users/` | Submodule (see `users/AGENTS.md`) |
27+
| `lib/` | Submodule (see `lib/AGENTS.md`) |
28+
29+
## For AI Agents
30+
### Working In This Directory
31+
Auto-scanned directory. Navigate inside for detailed structure if needed.
32+
33+
### Dependencies
34+
Based on global project settings.
35+
36+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎apps/api/src/admin/AGENTS.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<!-- Parent: ../../../../AGENTS.md -->
2+
<!-- Generated: 2026-03-02T14:47:05+11:00 | Updated: 2026-03-02T14:47:05+11:00 -->
3+
4+
# admin
5+
6+
## Purpose
7+
admin Basic components of the system (auto-generated)
8+
9+
## Key Files
10+
| File | Description |
11+
|------|-------------|
12+
| `service.py` | Refer to feature details |
13+
| `__init__.py` | Refer to feature details |
14+
| `model.py` | Refer to feature details |
15+
| `schemas.py` | Refer to feature details |
16+
| `router.py` | Refer to feature details |
17+
| `repository.py` | Refer to feature details |
18+
19+
## Subdirectories
20+
| Directory | Purpose |
21+
|-----------|---------|
22+
| - | No submodules |
23+
24+
## For AI Agents
25+
### Working In This Directory
26+
Auto-scanned directory. Navigate inside for detailed structure if needed.
27+
28+
### Dependencies
29+
Based on global project settings.
30+
31+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

0 commit comments

Comments
 (0)