Move library

.devops/js-tools/README.md

@@ -29,9 +29,9 @@ Review the diff after `lint:fix`; not every rule is safely fixable.
 ## Count Tokens
 
 The token tally helper writes reports to `dist/TOKEN_TALLY.md` and
-`dist/TOKEN_TALLY.json`. It tracks `.agents/rules/*.md`,
-`.agents/commands/*.md`, `.agents/skills/*/SKILL.md`, and
-`.agents/skills/*/agents/*.md`. YAML front matter metadata is excluded from
+`dist/TOKEN_TALLY.json`. It tracks `src/rules/*.md`,
+`src/commands/*.md`, `src/skills/*/SKILL.md`, and
+`src/skills/*/agents/*.md`. YAML front matter metadata is excluded from
 token counts for every tracked Markdown file; files without front matter are
 counted in full.
 

.devops/js-tools/scripts/comment-library-token-diff.mjs

@@ -48,7 +48,7 @@ async function changedLibraryFiles() {
     "--find-renames",
     `${baseRef}...${headRef}`,
     "--",
-    ".agents/",
+    "src/",
   ]);
 
   const rows = [];
@@ -57,8 +57,8 @@ async function changedLibraryFiles() {
     const status = fields[0];
     const basePath = status.startsWith("R") ? fields[1] : fields[1] ?? fields[0];
     const headPath = status.startsWith("R") ? fields[2] : fields[1] ?? fields[0];
-    const baseInLibrary = basePath?.startsWith(".agents/");
-    const headInLibrary = headPath?.startsWith(".agents/");
+    const baseInLibrary = basePath?.startsWith("src/");
+    const headInLibrary = headPath?.startsWith("src/");
     const displayPath = headInLibrary ? headPath : basePath;
 
     if (!baseInLibrary && !headInLibrary) continue;
@@ -81,7 +81,7 @@ async function changedLibraryFiles() {
 }
 
 function isEvalPath(path) {
-  return path?.startsWith(".agents/") && path.split("/").includes("evals");
+  return path?.startsWith("src/") && path.split("/").includes("evals");
 }
 
 function statusLabel(status) {
@@ -131,7 +131,7 @@ function renderComment(rows) {
   const marker = "<!-- library-token-diff -->";
   if (rows.length === 0) {
     return `${marker}
-No \`.agents/\` file token changes detected.
+No \`src/\` file token changes detected.
 `;
   }
 
@@ -148,7 +148,7 @@ No \`.agents/\` file token changes detected.
   return `${marker}
 ## Library Token Diff
 
-Estimated token changes for files under \`.agents/\`.
+Estimated token changes for files under \`src/\`.
 
 | File | Status | Before | After | Delta |
 | --- | --- | ---: | ---: | ---: |

.devops/js-tools/scripts/count-tokens.mjs

@@ -80,8 +80,8 @@ async function buildTokenReport() {
 
 async function trackedFiles() {
   return [
-    ...(await markdownEntries("command", ".agents/commands")),
-    ...(await markdownEntries("rule", ".agents/rules")),
+    ...(await markdownEntries("command", "src/commands")),
+    ...(await markdownEntries("rule", "src/rules")),
     ...(await skillEntries()),
     ...(await agentEntries()),
   ];
@@ -103,13 +103,13 @@ async function markdownEntries(kind, directory) {
 }
 
 async function skillEntries() {
-  const skillsDirectory = join(repoRoot, ".agents/skills");
+  const skillsDirectory = join(repoRoot, "src/skills");
   const skills = await readdir(skillsDirectory, { withFileTypes: true });
   const entries = await Promise.all(
     skills.filter((skill) => skill.isDirectory()).map(async (skill) => ({
       kind: "skill",
       name: skill.name,
-      path: `.agents/skills/${skill.name}/SKILL.md`,
+      path: `src/skills/${skill.name}/SKILL.md`,
       exists: await fileExists(join(skillsDirectory, skill.name, "SKILL.md")),
     })),
   );
@@ -120,7 +120,7 @@ async function skillEntries() {
 
 async function agentEntries() {
   const agents = [];
-  const skillsDirectory = join(repoRoot, ".agents/skills");
+  const skillsDirectory = join(repoRoot, "src/skills");
   const skills = await readdir(skillsDirectory, { withFileTypes: true });
 
   for (const skill of skills.filter((entry) => entry.isDirectory())) {
@@ -137,7 +137,7 @@ async function agentEntries() {
       agents.push({
         kind: "agent",
         name: `${skill.name}/${name}`,
-        path: `.agents/skills/${skill.name}/agents/${file.name}`,
+        path: `src/skills/${skill.name}/agents/${file.name}`,
       });
     }
   }

.github/workflows/labels.yml

@@ -34,10 +34,10 @@ jobs:
           {"name": "stale", "color": "848d97", "description": "No activity, may auto-close"},
           {"name": "declined", "color": "e6e6e6", "description": "Will not be implemented"},
           {"name": "playbook", "color": "0075ca", "description": "Core AGENTS.md playbook model and compatibility guidance"},
-          {"name": "rules", "color": "d4c5f9", "description": "Reusable rule files under .agents/rules"},
+          {"name": "rules", "color": "d4c5f9", "description": "Reusable rule files under src/rules"},
           {"name": "skills", "color": "a2eeef", "description": "Reusable skill specs and skill authoring guidance"},
-          {"name": "commands", "color": "bfd4f2", "description": "Slash command definitions under .agents/commands"},
-          {"name": "memory", "color": "c2e0c6", "description": "Agent memory conventions and .agents/memory content"},
+          {"name": "commands", "color": "bfd4f2", "description": "Slash command definitions under src/commands"},
+          {"name": "memory", "color": "c2e0c6", "description": "Agent memory conventions and src/memory content"},
           {"name": "documentation", "color": "bfdadc", "description": "Task-scoped docs, PRDs, specs, and implementation notes"},
           {"name": "site", "color": "fef2c0", "description": "GitHub Pages content, config, and assets"},
           {"name": "automation", "color": "fbca04", "description": "GitHub Actions, hooks, and repository automation"},

.github/workflows/library-token-diff.yml

@@ -8,7 +8,7 @@ on:
       - reopened
       - ready_for_review
     paths:
-      - ".agents/**"
+      - "src/**"
 
 permissions:
   contents: read

.gitignore

@@ -496,6 +496,6 @@ $RECYCLE.BIN/
 # End of https://www.toptal.com/developers/gitignore/api/linux,macos,dotenv,python,windows,intellij+all,visualstudiocode,node
 
 # Evaluation output quality files
-.agents/**/evals/*
-!.agents/**/evals/evals.json
-!.agents/**/evals/evals.yaml
+src/**/evals/*
+!src/**/evals/evals.json
+!src/**/evals/evals.yaml

AGENTS.md

@@ -38,23 +38,23 @@ docs/                          # Project-scoped documentation
 
 - Folder names: lowercase, hyphenated — e.g. `user-auth`, `payment-v2`, `issue-142`
 - Create a docs task folder only when the work needs durable task-scoped documentation such as `PRD.md`, `SPEC.md`, `ARCHITECTURE.md`, or `DESIGN.md`
-- Small task checklists and completed implementation notes belong in `.agents/memory/YYYY-MM-DD.md`
+- Small task checklists and completed implementation notes belong in `src/memory/YYYY-MM-DD.md`
 
 ## Loaded Context
 
 **Memory is useful, but verification wins.**
 
 | File | Purpose | Auto-load |
 | --- | --- | --- |
-| .agents/memory/MEMORY.md | Durable project facts and decisions | yes |
-| .agents/memory/YYYY-MM-DD.md | Daily task notes and observations | on-demand |
+| src/memory/MEMORY.md | Durable project facts and decisions | yes |
+| src/memory/YYYY-MM-DD.md | Daily task notes and observations | on-demand |
 
 ## Working on a task
 
 **Match the tracking weight to the work.**
 
 - For substantial work, create a task folder before writing code: `mkdir docs/$(date +%Y-%m-%d)-my-feature`
-- For small work, track the checklist in `.agents/memory/$(date -u +%Y-%m-%d).md`
+- For small work, track the checklist in `src/memory/$(date -u +%Y-%m-%d).md`
 - Use `TASKS.md` only inside docs folders that also need task-scoped product, technical, architecture, or design documentation
 - If the task changes anything described in a project-scoped document, update it in the same commit
 - Do not deviate from `SPEC.md` silently — update the file if the spec changes

README.md

@@ -5,7 +5,7 @@
 
 > A portable, tool-agnostic file structure playbook for LLM agents in software projects.
 
-Agent behavior is code. It should be versioned, reviewed, modular, and readable by both humans and machines. The `.agents/` folder is the single source of truth for everything an LLM agent needs to operate within a project — permissions, instructions, skills, memory, commands, and documentation artifacts.
+Agent behavior is code. It should be versioned, reviewed, modular, and readable by both humans and machines. The `src/` folder is the single source of truth for everything an LLM agent needs to operate within a project — permissions, instructions, skills, memory, commands, and documentation artifacts.
 
 ## Overview
 
@@ -16,11 +16,11 @@ This playbook gives agents — and the humans working alongside them — a consi
 ## Features
 
 - **`AGENTS.md`** — Primary instruction file and manifest. Every runtime loads this first.
-- **`.agents/rules/`** — Modular, composable instruction files.
-- **`.agents/skills/`** — Auto-invoking workflows triggered by events or file patterns.
-- **`.agents/commands/`** — Explicit slash commands.
-- **`.agents/agents/`** — Subagent personas invoked by `@mention`.
-- **`.agents/memory/`** — Persistent, append-only memory across sessions.
+- **`src/rules/`** — Modular, composable instruction files.
+- **`src/skills/`** — Auto-invoking workflows triggered by events or file patterns.
+- **`src/commands/`** — Explicit slash commands.
+- **`src/agents/`** — Subagent personas invoked by `@mention`.
+- **`src/memory/`** — Persistent, append-only memory across sessions.
 - **`docs/`** — Task-scoped documentation with standardized layout (PRD, SPEC, ARCHITECTURE, TASKS).
 
 ## Core Principles
@@ -35,7 +35,7 @@ This playbook gives agents — and the humans working alongside them — a consi
 
 ```text
 agent.md/              # ← this repository
-├── .agents/           # Maintained agent asset library
+├── src/           # Maintained agent asset library
 ├── docs/              # Task-scoped documentation
 ├── pages/             # GitHub Pages source
 │   ├── _config.yml    # GitHub Pages configuration
@@ -73,13 +73,13 @@ Add `skills/`, `commands/`, `agents/`, and `docs/` as the project matures.
 
 ### Library
 
-This repository maintains its primary reusable agent assets in [`.agents/`](./.agents):
+This repository maintains its primary reusable agent assets in [`src/`](./.agents):
 
-- **Rules** — `.agents/rules/formatting-markdown.md`
-- **Skills** — `.agents/skills/on-new-example/SKILL.md`
-- **Commands** — `.agents/commands/validate.md`
-- **Agents** — `.agents/agents/spec-reviewer.md`
-- **Memory** — `.agents/memory/MEMORY.md`
+- **Rules** — `src/rules/formatting-markdown.md`
+- **Skills** — `src/skills/on-new-example/SKILL.md`
+- **Commands** — `src/commands/validate.md`
+- **Agents** — `src/agents/spec-reviewer.md`
+- **Memory** — `src/memory/MEMORY.md`
 
 ### Real project layout
 
@@ -121,7 +121,7 @@ project-root/
 
 ## Development
 
-This repo uses itself to govern its own development — the `.agents/` folder is the maintained set of playbook-conformant assets used for that work.
+This repo uses itself to govern its own development — the `src/` folder is the maintained set of playbook-conformant assets used for that work.
 
 ```bash
 # No build step required. All content is plain Markdown.

docs/2026-05-02-team-roles-as-skills/PRD.md

@@ -36,7 +36,7 @@ The initiative targets teams and individual practitioners who want role-aware AI
 | Goal ID | Target Outcome | Success Metric |
 | --- | --- | --- |
 | G-1 | Cover the core artifact-producing responsibilities of a software delivery team. | 55 cataloged skills exist across the approved verb groups. |
-| G-1a | Track current implementation progress against the catalog. | 10 of 55 catalog skills currently exist in `.agents/skills/`; current catalog completion is 18%. |
+| G-1a | Track current implementation progress against the catalog. | 10 of 55 catalog skills currently exist in `src/skills/`; current catalog completion is 18%. |
 | G-2 | Make skill discovery predictable from the filesystem. | 100% of catalog skills follow the `<verb>-<subject>[-<variant>]` naming convention. |
 | G-3 | Reduce repeated role-specific prompting. | Users can invoke each completed skill by artifact or task intent without restating its output structure or role conventions. |
 | G-4 | Produce concrete, reusable artifacts instead of generic advice. | Every completed skill description names the artifact it produces and when it should trigger. |
@@ -87,12 +87,12 @@ The initiative targets teams and individual practitioners who want role-aware AI
 
 | Requirement ID | Capability / Feature | Priority | Acceptance Criteria | Tracker |
 | --- | --- | --- | --- | --- |
-| FR-1 | Define and track the full team-role skill catalog. | MUST | Catalog includes 55 named skills; each skill maps to at least one primary role and one output artifact; implementation status is checked against `.agents/skills/`; catalog stays aligned across PRD, SPEC, and TASKS. | [TASKS.md](TASKS.md) |
+| FR-1 | Define and track the full team-role skill catalog. | MUST | Catalog includes 55 named skills; each skill maps to at least one primary role and one output artifact; implementation status is checked against `src/skills/`; catalog stays aligned across PRD, SPEC, and TASKS. | [TASKS.md](TASKS.md) |
 | FR-2 | Enforce verb-first skill naming. | MUST | Every skill name follows `<verb>-<subject>[-<variant>]`; verbs match the approved verb list in SPEC.md; renames are reflected in docs and task tracking. | [SPEC.md](SPEC.md) |
 | FR-3 | Provide a standard skill structure. | MUST | Each skill has a `SKILL.md` with valid frontmatter; each skill has eval coverage; large reusable guidance lives in `references/` instead of bloating `SKILL.md`. | [SPEC.md](SPEC.md) |
 | FR-4 | Support multi-variant routing where domains share one role context. | SHOULD | Router skills detect variants from prompt and repo context; router skills ask at most one clarifying question when context is materially ambiguous; variant references are loaded on demand. | [SPEC.md](SPEC.md) |
 | FR-5 | Prioritize build order by daily leverage and role coverage. | MUST | P1 foundation skills are built first; P2/P3/P4 priorities are visible in TASKS.md; completed skills are marked in the tracker. | [TASKS.md](TASKS.md) |
-| FR-6 | Package completed skills for distribution. | SHOULD | Completed skills can be exported as `.skill` files; package contents include instructions, references, scripts, and assets needed for reuse; root-level evals are retained in the source folder and excluded from packaged artifacts by the current packager. | [SPEC.md](SPEC.md), [.agents/skills/README.md](../../.agents/skills/README.md) |
+| FR-6 | Package completed skills for distribution. | SHOULD | Completed skills can be exported as `.skill` files; package contents include instructions, references, scripts, and assets needed for reuse; root-level evals are retained in the source folder and excluded from packaged artifacts by the current packager. | [SPEC.md](SPEC.md), [src/skills/README.md](../../src/skills/README.md) |
 | FR-7 | Keep security and test responsibilities separated. | MUST | `audit-security` owns prompt-injection, jailbreak, exfiltration, secrets, and threat-modeling guidance; `code-tests` owns functional tests, AI evals, tool-use evals, performance tests, and CI test setup. | [SPEC.md](SPEC.md) |
 
 ---
@@ -165,7 +165,7 @@ For multi-variant skills, the expected interaction is context-first routing. For
 | --- | --- | --- | --- | --- |
 | DEC-1 | Use milestone gates instead of a fixed calendar date for the first complete catalog release. | The release is ready when all 55 cataloged skills are implemented, evaluated, documented, and packageable; 10 catalog skills are implemented as of 2026-05-23. | Oleg Shulyakov [assumed] | 2026-05-23 |
 | DEC-2 | Use the `create-skill` eval bar: 8-10 realistic eval prompts for focused skills and 8-10 prompts per routed reference for router skills. | This keeps the PRD aligned with the maintained authoring workflow while allowing specialized skills to add cases for variant coverage, boundary-trigger testing, or safety-sensitive behavior. | Skill maintainers [assumed] | 2026-05-23 |
-| DEC-3 | Package release-ready skills from `.agents/skills/create-skill` with `python3 -m scripts.package_skill ../<skill-name> /tmp/skills-dist`. | Release readiness requires `validate.py` to pass, evals to be present in source and pass at least an 85% aggregate expectation pass rate with no failed critical expectations, router evals to include `reference` fields, references to be useful, and no security or packaging blockers to remain. | Skill maintainers [assumed] | 2026-05-23 |
+| DEC-3 | Package release-ready skills from `src/skills/create-skill` with `python3 -m scripts.package_skill ../<skill-name> /tmp/skills-dist`. | Release readiness requires `validate.py` to pass, evals to be present in source and pass at least an 85% aggregate expectation pass rate with no failed critical expectations, router evals to include `reference` fields, references to be useful, and no security or packaging blockers to remain. | Skill maintainers [assumed] | 2026-05-23 |
 | DEC-4 | Treat organization-level convention packs as a separate follow-up. | This initiative ships the base local skill library first; organization convention packs should layer on later once the base format and release checks are stable. | Oleg Shulyakov [assumed] | 2026-05-23 |
 
 ---
@@ -174,4 +174,4 @@ For multi-variant skills, the expected interaction is context-first routing. For
 
 - **Ref-1**: Technical specification - [SPEC.md](SPEC.md)
 - **Ref-2**: Build tracker - [TASKS.md](TASKS.md)
-- **Ref-3**: Daily memory note for prior catalog updates - [.agents/memory/2026-05-18.md](../../.agents/memory/2026-05-18.md)
+- **Ref-3**: Daily memory note for prior catalog updates - [src/memory/2026-05-18.md](../../src/memory/2026-05-18.md)