Merge pull request #13 from PR0M3TH3AN/codex/add-skills-folder-and-weekly-prompt

Add skills onboarding docs and weekly repo-fit agent prompt

README.md

@@ -27,6 +27,8 @@ Create a `torch-config.json` file in your project root (or set `TORCH_CONFIG_PAT
 - `dashboard.defaultStatusView` (`active` or `all`)
 - `scheduler.firstPromptByCadence.daily` / `.weekly`
 
+Weekly alignment maintenance is available via `src/prompts/weekly/repo-fit-agent.md`, which is designed to keep TORCH defaults and docs tuned to the host repository over time.
+
 Default first-run behavior is configured so daily scheduling starts with `scheduler-update-agent`.
 
 Optional dashboard:
@@ -41,6 +43,7 @@ npm run dashboard:serve
 - `src/nostr-lock.mjs` — Generic lock/check/list CLI
 - `src/docs/TORCH.md` — Protocol summary and usage
 - `src/prompts/` — Generic scheduler prompts and flow
+- `skills/` — Repository-local skill guides for agent onboarding and repeatable workflows
 - `examples/` — Optional scheduler overlay examples for adapting TORCH to downstream repositories
 - `dashboard/index.html` — Static lock dashboard
 

skills/README.md

@@ -0,0 +1,26 @@
+# Agent Skills
+
+This folder is a lightweight, repository-local learning path for agents.
+
+Use it to store reusable skill guides that help agents complete tasks in this repository without rediscovering context.
+
+## How agents should use this folder
+
+1. Start with `skills/torch-basics.md` for the default TORCH workflow.
+2. Open only the skill file that matches the current task.
+3. Follow the skill exactly, then fall back to `AGENTS.md` and `CLAUDE.md` for unresolved questions.
+
+## Skill file template
+
+Each skill should stay generic and include:
+
+- **Purpose**
+- **When to use**
+- **Inputs needed**
+- **Steps**
+- **Validation**
+- **Output expectations**
+
+## Current skills
+
+- `torch-basics.md` — baseline setup, scheduler flow, and validation commands for this repository.

skills/torch-basics.md

@@ -0,0 +1,46 @@
+# Skill: TORCH Basics
+
+## Purpose
+
+Provide a repeatable baseline for agents who need to run TORCH scheduler and lock workflows safely.
+
+## When to use
+
+- Starting a new task in this repository.
+- Updating scheduler prompts or roster files.
+- Verifying lock and prompt configuration changes.
+
+## Inputs needed
+
+- Repository root access.
+- `torch-config.json` (optional if defaults are acceptable).
+- Agent identity and cadence (`daily` or `weekly`).
+
+## Steps
+
+1. Read baseline policy files:
+   - `AGENTS.md`
+   - `CLAUDE.md`
+   - `CONTRIBUTING.md`
+   - `KNOWN_ISSUES.md`
+2. Inspect scheduler assets:
+   - `src/prompts/roster.json`
+   - `src/prompts/daily-scheduler.md`
+   - `src/prompts/weekly-scheduler.md`
+3. Validate lock preflight for selected cadence:
+   - `npm run lock:check:daily` or `npm run lock:check:weekly`
+4. If needed, claim a lock for the working agent:
+   - `AGENT_PLATFORM=codex npm run lock:lock -- --agent <agent-name> --cadence <daily|weekly>`
+5. Run the selected prompt and complete repository checks relevant to changed files.
+
+## Validation
+
+- Confirm changed prompt names exist in `src/prompts/roster.json`.
+- Confirm scheduler docs list the same roster entry names.
+- Run at least one targeted command relevant to the change.
+
+## Output expectations
+
+- Minimal patch scoped to requested work.
+- Updated docs when workflow behavior changes.
+- Clear commit + PR summary including validations.

src/docs/TORCH.md

@@ -54,6 +54,8 @@ Common settings:
 
 Default first-run daily scheduler prompt is `scheduler-update-agent`.
 
+For weekly repository-fit maintenance, TORCH also includes `src/prompts/weekly/repo-fit-agent.md` to periodically adjust defaults and docs to the host repository.
+
 ## Roster precedence
 
 The lock CLI resolves roster names in this order:

src/prompts/roster.json

@@ -38,6 +38,7 @@
     "smoke-agent",
     "telemetry-agent",
     "test-coverage-agent",
+    "repo-fit-agent",
     "weekly-synthesis-agent"
   ]
 }

src/prompts/weekly-scheduler.md

@@ -30,4 +30,5 @@ Canonical roster source: `src/prompts/roster.json` (`weekly` key).
 | 13 | smoke-agent | `smoke-agent.md` |
 | 14 | telemetry-agent | `telemetry-agent.md` |
 | 15 | test-coverage-agent | `test-coverage-agent.md` |
-| 16 | weekly-synthesis-agent | `weekly-synthesis-agent.md` |
+| 16 | repo-fit-agent | `repo-fit-agent.md` |
+| 17 | weekly-synthesis-agent | `weekly-synthesis-agent.md` |

src/prompts/weekly/repo-fit-agent.md

@@ -0,0 +1,51 @@
+You are: **repo-fit-agent**, a weekly maintenance agent that keeps TORCH aligned with the downstream repository it is used in.
+
+Mission: review repository context and apply small, safe updates so TORCH defaults, prompts, and documentation better match the host project's current workflows.
+
+---
+
+## Scope
+
+Prioritize lightweight, high-signal alignment changes such as:
+
+- `torch-config.json` defaults that should be tuned for the host repository.
+- Scheduler prompt wording that should better reflect the host repository's branch, test, or logging conventions.
+- Documentation updates in `README.md`, `src/docs/TORCH.md`, or prompt docs when behavior has drifted.
+
+Avoid large refactors or product-specific hardcoding.
+
+---
+
+## Weekly workflow
+
+1. Read policy and workflow docs:
+   - `AGENTS.md`
+   - `CLAUDE.md`
+   - `CONTRIBUTING.md`
+   - `KNOWN_ISSUES.md`
+2. Compare current scheduler assets and defaults:
+   - `torch-config.json`
+   - `src/prompts/roster.json`
+   - `src/prompts/daily-scheduler.md`
+   - `src/prompts/weekly-scheduler.md`
+3. Identify 1–3 alignment gaps between TORCH defaults and the host repository's real workflow.
+4. Implement only the smallest safe updates needed.
+5. Run targeted validation for touched files.
+6. Summarize assumptions and follow-ups in the PR notes.
+
+---
+
+## Guardrails
+
+- Keep wording generic unless host-specific details are required.
+- Preserve backward compatibility whenever possible.
+- If uncertain, prefer documenting a recommendation over making a risky default change.
+- Do not claim validation that was not executed.
+
+---
+
+## Output expectations
+
+- Small, focused patch.
+- Updated documentation when behavior or workflow guidance changes.
+- Validation commands and outcomes recorded in final summary.