@codeyam/codeyam-cli 0.1.0-staging.b8a55ba → 0.1.0-staging.b8b17a5

package/codeyam-cli/templates/nextjs-prisma-supabase/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/codeyam-cli/templates/prompts/conversation-guidance.txt

@@ -0,0 +1,44 @@
+### What to look for
+
+Read the full transcript for these signals:
+
+**User corrections or redirections**
+- "no", "actually", "that's not right", "you need to also...", "you missed..."
+- User provides information Claude didn't know or couldn't infer from code
+- User reminds Claude of a step, pattern, or relationship
+- A correction about something other than current task requirements is ALWAYS rule-worthy
+
+**Investigation and debugging**
+- Claude tried multiple approaches, read logs, or tested hypotheses
+- Investigation revealed non-obvious behavior or root causes
+- Debugging strategies that worked (or didn't) for specific areas
+
+**Architecture not evident in code**
+- Files that must change together (templates + installation, routes + registration)
+- Complex files, data flows, pipelines, or system interactions that would benefit from an overview
+
+**Commands and workflows**
+- Specific commands or flags needed for this area
+- Order of operations that matters ("must run X before Y")
+
+**Ignore:**
+- Corrections to requirements for the current feature or bug
+- Confusion isolated to the current work session (won't recur)
+
+### Before creating a rule
+
+**Critical check:** Read the actual source files that were modified. If the code already contains comments, guard patterns, or tests that explain the insight, the code is the documentation — skip the rule unless the file is complex and you've made a mistake or the user had to interrupt and correct you.
+
+Show your thinking before proceeding with creating or updating rules.
+
+### How to write rules
+
+**Rules must be forward-looking, not historical.** You are reading a session transcript where bugs were found and fixed, but the rule should describe the *current* codebase, not tell the story of what went wrong, what was fixed, etc. The code has already been updated — past bugs are no longer relevant.
+
+- **DO**: State constraints and requirements ("this script MUST copy directories recursively, not just files")
+- **DO**: Explain *why* something matters ("errors in prompt copying are silently caught, so missing directories won't surface as errors")
+- **DON'T**: Describe what old code did ("the old version only copied files, causing X to be missing")
+- **DON'T**: Narrate the debugging journey ("we discovered that the catch block was swallowing errors")
+- **DON'T**: Note issues or known gaps if they are actively being worked on!
+
+Think of the reader as a developer about to modify these files. They need to know what constraints to preserve and what pitfalls to watch for — not what happened in the past if it is no longer relevant.

package/codeyam-cli/templates/prompts/conversation-prompt.txt

@@ -0,0 +1,28 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+Analyze the conversation transcript for rule-worthy learnings:
+- User corrections, redirections, or information Claude didn't know
+- Investigation results and debugging knowledge
+- Architecture and relationships not obvious from code
+- Commands, workflows, and processes
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/prompts/interruption-prompt.txt

@@ -0,0 +1,31 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+The user interrupted Claude mid-response — a strong signal of confusion or misunderstanding.
+Analyze both Claude's interrupted output and the user's follow-up to determine what went wrong.
+
+Look for:
+- Claude heading in a wrong direction that the user had to correct
+- Misunderstanding of project conventions, architecture, or dependencies
+- Missing context that caused Claude to make incorrect assumptions
+- Patterns that would recur in future sessions without a rule
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/prompts/stale-rules-prompt.txt

@@ -0,0 +1,24 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+For each stale rule:
+1. Review the inline rule content and the diff to determine if the rule needs updating
+2. If it needs updating, edit the rule file in .claude/rules/ — also trim prose and unnecessary headers (most rules should be a few bullets)
+3. Run `codeyam memory touch <rule-path1> <rule-path2> ...` with the SPECIFIC rule paths you reviewed to mark them as audited in .claude/codeyam-rule-state.json
+   Example: `codeyam memory touch tooling/cli-build.md packages/ai/execution-flow-prioritization.md`
+
+Write a summary to `{{NOTIFICATION_FILE}}` listing each action taken, even if you only ran `codeyam memory touch` without content changes. Example:
+```
+The background rule-reflection agent updated the following rules:
+- Reviewed `.claude/rules/example.md` — no content changes, ran `codeyam memory touch`
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory), NOT ~/.claude/rules/ (the user home directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/rule-notification-hook.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook: surfaces rule-reflection notifications to the main session.
+
+The background rule-reflection agents write summaries to notification files
+in /tmp/claude-rule-markers/ when they create or update rules.
+This hook checks for those files on each user message, prints them to stdout
+(which Claude sees as injected context), and deletes them.
+
+Supports four notification files (legacy combined + split agents):
+- rule-notification.md (legacy/backward-compat)
+- rule-notification-stale.md (stale rules agent)
+- rule-notification-conversation.md (conversation review agent)
+- rule-notification-interruption.md (interruption review agent)
+"""
+
+import json
+import os
+import sys
+
+MARKER_DIR = '/tmp/claude-rule-markers'
+NOTIFICATION_FILES = [
+    'rule-notification.md',
+    'rule-notification-stale.md',
+    'rule-notification-conversation.md',
+    'rule-notification-interruption.md',
+]
+
+
+def get_project_slug():
+    """
+    Derive project slug from .codeyam/config.json (matching getProjectSlug() on the TS side).
+    Falls back to os.path.basename(project_dir) if config is absent or malformed.
+    """
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+    try:
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        slug = config.get('projectSlug', '')
+        if slug:
+            return slug
+    except (IOError, json.JSONDecodeError, KeyError):
+        pass
+    return os.path.basename(project_dir)
+
+
+def main():
+    collected = []
+    slug = get_project_slug()
+
+    # Check slug subdirectory first, then fall back to flat directory
+    dirs_to_check = [os.path.join(MARKER_DIR, slug), MARKER_DIR]
+
+    for filename in NOTIFICATION_FILES:
+        for check_dir in dirs_to_check:
+            filepath = os.path.join(check_dir, filename)
+            if not os.path.exists(filepath):
+                continue
+
+            try:
+                with open(filepath, 'r') as f:
+                    content = f.read().strip()
+            except IOError:
+                continue
+
+            if content:
+                collected.append(content)
+
+            try:
+                os.remove(filepath)
+            except OSError:
+                pass
+
+            # Found in this directory — don't check the fallback
+            break
+
+    if collected:
+        print('\n\n'.join(collected))
+
+
+if __name__ == '__main__':
+    main()