From b26a94d7799419c373bc8b4c4dae35da55c9e48e Mon Sep 17 00:00:00 2001
From: bastien <git@bchanot.fr>
Date: Wed, 6 May 2026 18:32:16 +0200
Subject: [PATCH] optimize(doc): add resources/templates/README.md.tpl +
 DEPLOY.md.tpl + reference (d6 target)

---
 skills/doc/SKILL.md                          | 13 ++++++
 skills/doc/resources/templates/DEPLOY.md.tpl | 49 ++++++++++++++++++++
 skills/doc/resources/templates/README.md.tpl | 35 ++++++++++++++
 3 files changed, 97 insertions(+)
 create mode 100644 skills/doc/resources/templates/DEPLOY.md.tpl
 create mode 100644 skills/doc/resources/templates/README.md.tpl

diff --git a/skills/doc/SKILL.md b/skills/doc/SKILL.md
index f12e118..3a1ecde 100644
--- a/skills/doc/SKILL.md
+++ b/skills/doc/SKILL.md
@@ -31,6 +31,19 @@ allowed-tools:
 Load and follow strictly:
 - $HOME/.claude/agents/doc-syncer.md
 
+## Resources
+
+The agent uses these reusable templates instead of inlining markdown each time:
+
+- `resources/templates/README.md.tpl` — GitHub-style README skeleton (title, quick start, sub-doc links, stack, license).
+- `resources/templates/DEPLOY.md.tpl` — Deploy doc skeleton (prereqs, build, deploy, verify, rollback, common failures).
+
+When the agent decides a doc must be created (STEP 5 / STEP 6 in the agent flow),
+read the matching template, substitute `{{PLACEHOLDERS}}` from project state
+(stack detection, manifest, env signals), and write to project root. Do not
+copy the placeholders verbatim — every `{{...}}` must be replaced or removed
+before writing.
+
 Execute the DOC SYNCER on this project.
 
 Context from the user (if any):
diff --git a/skills/doc/resources/templates/DEPLOY.md.tpl b/skills/doc/resources/templates/DEPLOY.md.tpl
new file mode 100644
index 0000000..24f140c
--- /dev/null
+++ b/skills/doc/resources/templates/DEPLOY.md.tpl
@@ -0,0 +1,49 @@
+# Deploy
+
+Stack: {{STACK}}
+Target: {{DEPLOY_TARGET}}<!-- e.g. Vercel, fly.io, Docker on VPS, k8s -->
+
+## Prerequisites
+
+- {{REQUIRED_TOOLS}}<!-- gh, fly, docker, kubectl, etc. -->
+- Environment variables set in {{ENV_LOCATION}}<!-- .env / Vercel dashboard / GH secrets -->
+
+## Build
+
+```bash
+{{BUILD_CMD}}
+```
+
+Verify the build artifact at `{{BUILD_OUTPUT_DIR}}` is non-empty before proceeding.
+
+## Deploy
+
+```bash
+{{DEPLOY_CMD}}
+```
+
+## Verify
+
+```bash
+{{HEALTH_CHECK_CMD}}<!-- curl /healthz or equivalent -->
+```
+
+Expected response: `{{EXPECTED_RESPONSE}}`.
+
+## Rollback
+
+```bash
+{{ROLLBACK_CMD}}<!-- e.g. fly releases rollback <id>, kubectl rollout undo, vercel rollback -->
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| {{SYMPTOM_1}} | {{CAUSE_1}} | {{FIX_1}} |
+| Build fails on `{{COMMON_BUILD_ERR}}` | Likely env var missing | Check {{ENV_LOCATION}} has {{REQUIRED_VARS}} |
+
+## Logs / monitoring
+
+- Logs: `{{LOG_CMD}}`
+- Monitoring: {{MONITORING_URL}}<!-- Grafana / Sentry / Vercel analytics -->
diff --git a/skills/doc/resources/templates/README.md.tpl b/skills/doc/resources/templates/README.md.tpl
new file mode 100644
index 0000000..dd4def4
--- /dev/null
+++ b/skills/doc/resources/templates/README.md.tpl
@@ -0,0 +1,35 @@
+# {{PROJECT_NAME}}
+
+> {{ONE_LINE_DESCRIPTION}}
+
+{{BADGES}}<!-- e.g. build status, license, version -->
+
+## Quick start
+
+```bash
+{{INSTALL_CMD}}
+{{BUILD_CMD}}
+{{RUN_CMD}}
+```
+
+## What's inside
+
+{{ONE_PARAGRAPH_OVERVIEW}}
+
+## Documentation
+
+{{DOC_INDEX}}<!-- bullet list of links to existing sub-docs -->
+- [Install](INSTALL.md){{IF_INSTALL}}
+- [Configure](CONFIGURE.md){{IF_CONFIGURE}}
+- [Usage](USAGE.md){{IF_USAGE}}
+- [Deploy](DEPLOY.md){{IF_DEPLOY}}
+- [Contributing](CONTRIBUTING.md){{IF_CONTRIBUTING}}
+- [Changelog](CHANGELOG.md){{IF_CHANGELOG}}
+
+## Stack
+
+{{STACK_BULLETS}}<!-- one bullet per language/framework with version -->
+
+## License
+
+{{LICENSE}}