docs: integrate /learn command and skill system into documentation suite

Author: apiad

docs/deploy.md

@@ -69,6 +69,10 @@ gemini /onboard
 
 Check the current `TASKS.md` file and use the `/task` command to define your project's initial goals.
 
+### 3. Codified Knowledge
+
+Knowledge mastered via `/learn` is stored in `.gemini/skills/`. These are permanent project assets and **must** be tracked in version control to ensure the AI's long-term memory persists across environments.
+
 ### 3. Start a New Feature
 
 For your first feature, follow the standard workflow:

docs/design.md

@@ -64,7 +64,19 @@ The `pre-commit.py` hook implements a sophisticated cross-file validation strate
 
 ### 4. Specialized Agents (`.gemini/agents/`)
 
-Instead of a single "do-it-all" AI, the framework delegates tasks to specialized sub-agents with restricted toolsets and focused personas (e.g., `planner`, `debugger`, `editor`, `reporter`). This ensures higher reliability and more consistent results.
+Instead of a single "do-it-all" AI, the framework delegates tasks to specialized sub-agents with restricted toolsets and focused personas.
+
+- **`planner`:** Responsible for high-level architectural design and roadmap generation.
+- **`debugger`:** A forensic investigation specialist using a scientific, hypothesis-driven workflow.
+- **`learner`:** A "Grounded Learning Specialist" who master new technologies by writing, executing, and documenting code experiments.
+- **`reporter` / `editor`:** Content generation and refinement specialists.
+
+### 5. The Skill System (`.gemini/skills/`)
+
+The framework's permanent knowledge base. Each skill is a directory containing:
+- **`SKILL.md`:** The entry point with mandatory YAML frontmatter (`name` and `description`) for autonomous activation.
+- **`reference-*.md`:** Granular documentation for specific learning objectives.
+- **`assets/`:** Idiomatic, verified code examples and experiment scripts.
 
 ### 4. State Management
 

docs/develop.md

@@ -56,9 +56,28 @@ Failure to do this will block your commit or turn execution.
 
 ## ✅ Testing & Quality Standards
 
+- **Agent-Driven Validation:** This project does **not** maintain a traditional suite of unit or integration tests (e.g., in a `tests/` directory). Instead, it relies on high-discipline agent execution and **Grounded Experimentation** to verify behavior.
 - **Source of Truth:** The `makefile` is the central definition of project health.
-- **Mandatory Commands:** Ensure `make test`, `make lint`, and `make format` pass before committing.
-- **Documentation-as-Code:** Any new feature must be accompanied by relevant updates to the `docs/` directory.
+- **TCR Protocol:** The primary mechanism for ensuring "Green-only" development is the mandatory **Test-Commit-Revert** loop during task execution.
+
+## 🧠 Codifying Knowledge with Skills
+
+The `/learn` command is the primary tool for expanding the project's knowledge base. All generated skills must adhere to the following structure:
+
+### 1. Mandatory Frontmatter (`SKILL.md`)
+
+The root `SKILL.md` file **must** include a YAML block at the top. This allows the framework to autonomously recognize and activate the skill in future sessions.
+
+```yaml
+---
+name: <unique-identifier>
+description: <concise-summary-for-autonomous-activation>
+---
+```
+
+### 2. Asset Management
+
+Move all successful experiment scripts and idiomatic examples to the `assets/` subdirectory within the skill folder.
 
 ## 🌲 Git & Source Control
 

docs/index.md

@@ -42,6 +42,7 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 ## 🛠️ Key Capabilities
 
 - **Deep Discovery:** Use `/research` for multi-phase domain investigations.
+- **Knowledge Mastering:** Use `/learn` to explore and codify new libraries or topics into permanent project skills.
 - **Architectural Planning:** Use `/plan` to generate persistent, actionable strategies.
 - **Forensic Debugging:** Use `/debug` for root-cause analysis without immediate (and potentially incorrect) fixes.
 - **Automated Documentation:** Use `/docs` to keep the documentation synchronized with the evolving codebase.

docs/user-guide.md

@@ -36,6 +36,17 @@ Your tool for internal strategy and architectural design.
 - **How it works:** The `planner` subagent conducts a thorough analysis of your codebase and journal. After clarifying the goal with you interactively, it produces a comprehensive Markdown plan in the `plans/` directory.
 - **Crucial Rule:** The `/plan` command *never* executes the code. It maps the territory and provides a step-by-step execution roadmap for you to approve first.
 
+### `/learn`
+
+Your tool for mastering new technologies and codifying them into project skills.
+
+- **How it works:** Implements a "Grounded Learning" philosophy through a 4-phase lifecycle:
+    1.  **Environment Audit:** Automatically detects if the library is already installed or has local integration points.
+    2.  **Strategic Mapping:** Researches the topic and defines 3-5 granular Learning Objectives (the "Learning Map"). **Requires user approval via `ask_user`.**
+    3.  **Grounded Execution:** The specialized `learner` sub-agent performs real-world experiments (writing and running scripts) to verify "gotchas," performance, and idiomatic patterns.
+    4.  **Skill Codification:** Consolidates all findings into a permanent project skill in `.gemini/skills/<name>/`, including a mandatory `SKILL.md` file and reference documents.
+- **Why it works:** It transforms ephemeral research into a permanent, machine-readable knowledge base that future agents can autonomously activate.
+
 ---
 
 ## 💻 The Software Development Workflow

journal/2026-03-20.md

@@ -21,3 +21,4 @@
 [2026-03-20T12:46:46] - Fixed SKILL.md formatting for pytest by adding YAML frontmatter.
 [2026-03-20T12:47:49] - Updated learn.toml command with explicit SKILL.md formatting instructions (YAML frontmatter).
 [2026-03-20T12:56:15] - Migrated tests to pytest, then cleaned up tests and makefile to finalize /learn command
+[2026-03-20T13:01:58] - Updated comprehensive documentation suite to include the new /learn command, grounded learning philosophy, and skill codification system