edit

Author: karaposu

SUMMARY.md

@@ -52,9 +52,10 @@
 
 ## Appendices
 
-* [Appendix 1: New Project Prompts](content/APPENDIX1_NEW_PROJECT_PROMPTS.md)
-* [Appendix 2: From Existing Codebase Prompts](content/APPENDIX2_FROM_EXISTING_CODEBASE_PROMPTS.md)
-* [Appendix 9: AlignStack Slash Commands](src/APPENDIX9_ALIGNSTACK_SLASH_COMMANDS.md)
+* [Appendix 1: New Project Prompts](content/APPENDIX1_New_Project_Prompts.md)
+* [Appendix 2: From Existing Codebase Prompts](content/APPENDIX2_From_Existing_Codebase_Prompts.md)
+* [Appendix 8: AlignStack Slash Commands](src/APPENDIX8_Alignstack_Slash_Commands.md)
+* [Appendix 9: DevDocs Folder Convention](src/APPENDIX9_Devdocs_Folder_Convention.md)
 
 ## Additional Resources
 

commands/arch-intro.md

@@ -19,6 +19,19 @@ $ARGUMENTS
 
 4. Be honest — if the architecture is inconsistent, messy, or in transition, say so. If patterns are partially applied, note it.
 
+### Metadata
+
+When saving to a file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
 ### Output
 
 **If `--save` is passed as an argument:**

commands/arch-small-summary.md

@@ -21,6 +21,19 @@ $ARGUMENTS
 
 4. Be honest about the state of things — if something looks half-built, say so. If something looks abandoned, note it.
 
+### Metadata
+
+When saving to a file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
 ### Output
 
 **If `--save` is passed as an argument:**

commands/arch-top-improvements.md

@@ -19,6 +19,19 @@ $ARGUMENTS
 
 4. Rank them by impact, highest first.
 
+### Metadata
+
+Before writing the file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
 ### Output
 
 Write to `devdocs/archaeology/top_improvements.md` (create the directory if needed). If the file already exists, overwrite it completely — rewrite fresh, don't patch.

commands/arch-traces.md

@@ -34,6 +34,19 @@ Each trace file must contain:
 - **What feels vulnerable**
 - **What feels like bad design**
 
+### Metadata
+
+Insert a metadata header at the very top of each trace file by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
 ### Output
 
 Write trace files to `devdocs/archaeology/traces/` (create the directory if needed). If the folder already exists, overwrite all trace files completely — rewrite fresh, don't patch.

commands/critic-d.md

@@ -63,6 +63,21 @@ For each identified risk item, document:
 | **Affected areas** | Which existing features, modules, or endpoints are affected |
 | **Mitigation** (Medium/High only) | Three levels: quick fix, robust fix, long-term fix |
 
+## Metadata
+
+Before writing any file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
+---
+
 ## Guidelines
 
 - Be specific. "This might cause performance issues" is useless. "Adding a full table scan in `getUsers()` on a table with 100k+ rows will degrade response time from ~50ms to ~2s" is useful.

commands/critic.md

@@ -90,6 +90,21 @@ Use the same output format (risk items with Severity, Impact, ELI5, Mitigation)
 
 ---
 
+## Metadata
+
+Before writing any file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
+---
+
 ## Guidelines
 
 - Be specific. "This might cause performance issues" is useless. "Adding a full table scan in `getUsers()` on a table with 100k+ rows will degrade response time from ~50ms to ~2s" is useful.

commands/elaborate.md

@@ -1,33 +1,49 @@
 # /elaborate — Rephrase for Alignment Verification
 
-Take the input below and rephrase it back to me — clearer, more structured, more understandable. Use your understanding of the codebase to interpret what I mean and fill in obvious gaps.
+Take the input below and rephrase it,  clearer, more structured, more understandable. Use your understanding of the already developed context (can be about codebase workspace, or past conversation regarding this topic etc) to interpret what the input material means and fill in obvious gaps to make it more explicit. 
+
+If you dont have any developed relevant context output that the elaboration will be done without relevant context in pure way in terminal as a warning. 
 
 ## Input
 
 $ARGUMENTS
 
 ## Instructions
 
-1. Parse the input. It can be:
-   - **Raw text only** — notes, a ticket, a data dump, or a loose description.
-   - **A file path only** — read the file and use its contents as the input.
-   - **A file path + additional text** — read the file first, then treat the remaining text as extra context or instructions on top of the file contents. Both parts matter.
+1. Consume the input fully and correctly. It can be markdown, file path with code or text files, image paths, MCP links. if file path is given 
 
-   If the input starts with something that looks like a file path (e.g. `devdocs/...`, `src/...`, or any path with `/`), attempt to read it as a file. Everything after the path is additional context.
+   - if file path is given read the files fully. .
+   - if file image or image paths are given consume the images
+   - additional text or commands should be respected as well. 
 
-2. Use codebase context to understand what the user is referring to (existing modules, patterns, terminology).
-3. Rephrase the input in clear, precise language. Make it structured and easy to follow — organize scattered thoughts, group related ideas, clarify vague phrasing. Keep the user's intent intact, don't reshape it into a format they didn't ask for.
+2. If relevant, use codebase context to understand what the content is referring to (existing modules, patterns, terminology).
+3. Rephrase the input in clear, precise language. Make it structured and easy to follow — organize scattered thoughts, group related ideas, clarify vague phrasing. Keep the content's intent intact, don't reshape it into a format they didn't ask for.
 4. After the rephrased version, add:
-   - **Ambiguities**: Anything that is unclear, has multiple interpretations, or needs a decision — list these explicitly.
+   - **Ambiguities Section**: Anything that is unclear for you, has multiple interpretations, or needs a decision to make sense of the rest of the material — list these explicitly in form of questions 
 
 ### Output
 
-5. Save the output as markdown file(s). Split into multiple files if the input covers distinct topics or is large enough to warrant it.
-   - **If the input was file path(s)** — save the elaborated output in the same folder as the input files.
-   - **Otherwise** — save under `devdocs/clarifications/<suitable-name>/` (create the directory if needed, use a short descriptive name based on the content).
-6. Print the output in the conversation as well.
-7. End with: *"Does this capture what you meant? Correct anything that's off before we proceed."*
+output this in devdocs as elaboration.md where the input source material is located in devdocs already. If input was not in devdocs then you can use mkdir command to create a subfolder with relevant name and create it there
+
+if the input covers distinct topics or is large enough to warrant it split into multiple files. But this is only needed if material is really huge and long. if this is the case under devdocs and relevant folder you can create elaboration folder and under it you can create multiple markdown files (use a short descriptive name based on the content).. But again, this is rare case. 
+
+## Metadata
+
+Before writing any file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
+---
 
 ## Purpose
 
 The primary goal is to take messy, scattered input and make it tidy — structured, clear, and easy to read. As a side effect, this also serves as an alignment check: if the rephrased version doesn't match intent, it gets caught here rather than three steps later. Only flag ambiguities that actually matter for moving forward — don't nitpick.
+
+

commands/install.sh

@@ -1,13 +1,19 @@
 #!/bin/bash
-# Install AlignStack slash commands for Claude Code
+# Install AlignStack slash commands and hooks for Claude Code
 # Usage: curl -sL https://raw.githubusercontent.com/karaposu/alignstack/main/commands/install.sh | bash
 
 set -e
 
-BASE_URL="https://raw.githubusercontent.com/karaposu/alignstack/main/commands"
-TARGET_DIR="$HOME/.claude/commands"
+REPO_URL="https://raw.githubusercontent.com/karaposu/alignstack/main"
+COMMANDS_DIR="$HOME/.claude/commands"
+HOOKS_DIR="$HOME/.claude/hooks"
 
-mkdir -p "$TARGET_DIR"
+mkdir -p "$COMMANDS_DIR"
+mkdir -p "$HOOKS_DIR"
+
+# --- Slash Commands ---
+
+echo "Installing slash commands..."
 
 commands=(
   elaborate.md
@@ -24,9 +30,32 @@ commands=(
 
 for cmd in "${commands[@]}"; do
   echo "  downloading $cmd"
-  curl -sL "$BASE_URL/$cmd" -o "$TARGET_DIR/$cmd"
+  curl -sL "$REPO_URL/commands/$cmd" -o "$COMMANDS_DIR/$cmd"
 done
 
+# --- Hooks ---
+
+echo ""
+echo "Installing hooks..."
+
+hooks=(
+  devdocs_metadata_appender.sh
+)
+
+for hook in "${hooks[@]}"; do
+  echo "  downloading $hook"
+  curl -sL "$REPO_URL/hooks/$hook" -o "$HOOKS_DIR/$hook"
+  chmod +x "$HOOKS_DIR/$hook"
+done
+
+# --- Summary ---
+
+echo ""
+echo "Done. Installed ${#commands[@]} slash commands to $COMMANDS_DIR"
+echo "Done. Installed ${#hooks[@]} hooks to $HOOKS_DIR"
+echo ""
+echo "Slash commands: /elaborate, /task-desc, /task-plan, /critic, /critic-d, /sense-making, /arch-small-summary, /arch-intro, /arch-traces, /arch-top-improvements"
+echo ""
+echo "To activate the devdocs metadata hook, add this to .claude/settings.json:"
 echo ""
-echo "Done. Installed ${#commands[@]} slash commands to $TARGET_DIR"
-echo "Available in Claude Code: /elaborate, /task-desc, /task-plan, /critic, /critic-d, /sense-making, /arch-small-summary, /arch-intro, /arch-traces, /arch-top-improvements"
+echo '  {"hooks":{"PreToolUse":[{"matcher":"Write","hooks":[{"type":"command","command":"~/.claude/hooks/devdocs_metadata_appender.sh"}]}]}}'

commands/sense-making.md

@@ -19,7 +19,18 @@ $ARGUMENTS
 
 3. Execute the full Structural Sensemaking process described below, producing all Sense Versions (SV1 through SV6).
 
-4. Save the output as a markdown file:
+4. Before writing any file, insert a metadata header at the very top by running `git branch --show-current`, `git rev-parse --short HEAD`, and `git config user.name` to populate:
+
+```
+---
+created: YYYY-MM-DD
+branch: <current branch>
+base_commit: <short HEAD commit>
+author: <git user.name>
+---
+```
+
+5. Save the output as a markdown file:
    - **If the input was a file path** — save in the same folder as the input file.
    - **Otherwise** — save under `devdocs/sensemaking/<suitable-name>.md` (create the directory if needed).