feat: add /learn command to extract session learnings to scoped AGENTS.md files

packages/opencode/src/command/index.ts

@@ -4,6 +4,7 @@ import { Config } from "../config/config"
 import { Instance } from "../project/instance"
 import { Identifier } from "../id/id"
 import PROMPT_INITIALIZE from "./template/initialize.txt"
+import PROMPT_LEARN from "./template/learn.txt"
 import PROMPT_REVIEW from "./template/review.txt"
 import { MCP } from "../mcp"
 
@@ -53,6 +54,7 @@ export namespace Command {
   export const Default = {
     INIT: "init",
     REVIEW: "review",
+    LEARN: "learn",
   } as const
 
   const state = Instance.state(async () => {
@@ -76,6 +78,15 @@ export namespace Command {
         subtask: true,
         hints: hints(PROMPT_REVIEW),
       },
+      [Default.LEARN]: {
+        name: Default.LEARN,
+        description: "create/update scoped AGENTS.md files after a session",
+        get template() {
+          return PROMPT_LEARN.replace("${path}", Instance.worktree)
+        },
+        subtask: true,
+        hints: hints(PROMPT_LEARN),
+      },
     }
 
     for (const [name, command] of Object.entries(cfg.command ?? {})) {

packages/opencode/src/command/template/learn.txt

@@ -0,0 +1,38 @@
+Analyze this session and extract non-obvious learnings to add to AGENTS.md files.
+
+AGENTS.md files can exist at any directory level, not just the project root. When an agent reads a file, any AGENTS.md in parent directories are automatically loaded into the context of the tool read. Place learnings as close to the relevant code as possible:
+
+- Project-wide learnings → ${path}/AGENTS.md
+- Package/module-specific → ${path}/packages/foo/AGENTS.md
+- Feature-specific → ${path}/src/auth/AGENTS.md
+
+What counts as a learning (non-obvious discoveries only):
+
+- Hidden relationships between files or modules
+- Execution paths that differ from how code appears
+- Non-obvious configuration, env vars, or flags
+- Debugging breakthroughs when error messages were misleading
+- API/tool quirks and workarounds
+- Build/test commands not in README
+- Architectural decisions and constraints
+- Files that must change together
+
+What NOT to include:
+
+- Obvious facts from documentation
+- Standard language/framework behavior
+- Things already in an AGENTS.md
+- Verbose explanations
+- Session-specific details
+
+Process:
+
+1. Review session for discoveries, errors that took multiple attempts, unexpected connections
+2. Determine scope - what directory does each learning apply to?
+3. Read existing AGENTS.md files at relevant levels
+4. Create or update AGENTS.md at the appropriate level
+5. Keep entries to 1-3 lines per insight
+
+After updating, summarize which AGENTS.md files were created/updated and how many learnings per file.
+
+$ARGUMENTS