feat: Add /project, /deploy, and /doc_sync commands#23
feat: Add /project, /deploy, and /doc_sync commands#23james-cantonwine wants to merge 2 commits into
Conversation
…gents Three new commands to address gaps in deployment operations, project navigation, and documentation freshness: /project [name] - Loads project context briefing (tech stack, git status, open issues/PRs, TODO items, key commands) to reduce context-switching cost across 6+ active production apps. Read-only, no new agents needed. /deploy [env] - Multi-platform deployment orchestration with 3 phases: pre-deploy checks (clean tree, tests, types, branch), platform-specific deploy (auto-detects AWS CDK, Railway, Cloudflare Workers, Amplify, Cloud Run, GitHub Pages), and post-deploy verification via new deploy-verifier agent. Requires user confirmation before executing. /doc_sync [project|all] - Documentation drift detector that cross-references CLAUDE.md and README.md against actual codebase. Checks file path validity, command runnability, dependency accuracy, env var consistency, and undocumented new content. Uses new documentation-auditor agent for analysis. Proposes fixes with user approval before editing. New agents: - deploy-verifier: Post-deployment smoke testing and health verification - documentation-auditor: Cross-references docs against code for drift detection
Summary of ChangesHello @james-cantonwine, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the developer experience by introducing three powerful new commands. These commands automate critical development workflows: providing instant project context, ensuring robust and verified deployments across diverse platforms, and maintaining documentation accuracy by detecting and helping to resolve drift. The changes aim to streamline operations, reduce manual errors, and keep project information consistent and up-to-date. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
@krishagel — Added 3 new commands and 2 supporting agents to fill gaps in deployment ops, project navigation, and documentation freshness. Details in the PR description. Let me know if you have any questions. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces several new commands and agents for project management, deployment, and documentation synchronization. The overall functionality is a great addition. I've identified a few areas for improvement, primarily focusing on enhancing the robustness and safety of the shell scripts. Key suggestions include making deployment environment selection explicit to prevent accidental production deploys, ensuring pre-deploy checks halt execution on failure, replacing unsafe ls parsing with more reliable methods, and fixing a few potential bugs in the scripts. Addressing these points will significantly improve the reliability and safety of these new commands.
| ### Phase 1: Environment & Project Detection | ||
|
|
||
| ```bash | ||
| DEPLOY_ENV="${ARGUMENTS:-prod}" |
There was a problem hiding this comment.
Defaulting the deployment environment to prod is extremely risky and can easily lead to accidental production deployments. The script should require an explicit environment argument and fail if it's not provided. This change is critical for preventing production accidents.
| DEPLOY_ENV="${ARGUMENTS:-prod}" | |
| DEPLOY_ENV="${ARGUMENTS:?ERROR: Deployment environment not specified. Please provide 'dev', 'staging', or 'prod'.}" |
| **File paths:** | ||
| ```bash | ||
| # For each path mentioned in docs, check existence | ||
| test -e "$PATH" && echo "✓ $PATH" || echo "✗ $PATH (MISSING)" |
There was a problem hiding this comment.
Using PATH as a variable name is dangerous as it shadows the system's $PATH environment variable, which is essential for locating executables. This can lead to command not found errors and other unpredictable behavior. It's crucial to use a different variable name, such as file_path, to avoid this conflict.
| test -e "$PATH" && echo "✓ $PATH" || echo "✗ $PATH (MISSING)" | |
| test -e "$file_path" && echo "✓ $file_path" || echo "✗ $file_path (MISSING)" |
| HAS_TEST=$(node -e "const p=require('./package.json'); console.log(p.scripts && p.scripts.test ? 'yes' : 'no')" 2>/dev/null) | ||
| if [ "$HAS_TEST" = "yes" ]; then | ||
| echo "Running tests..." | ||
| bun test 2>&1 || npm test 2>&1 || echo "❌ FAIL: Tests failed" |
There was a problem hiding this comment.
The pre-deploy test check for Node.js projects only prints a failure message but does not stop the script. This contradicts the instruction to "Stop and report if any fail." A failed test run should immediately halt the deployment process to prevent deploying broken code.
| bun test 2>&1 || npm test 2>&1 || echo "❌ FAIL: Tests failed" | |
| (bun test || npm test) || { echo "❌ FAIL: Tests failed. Aborting deployment."; exit 1; } |
| fi | ||
| elif [ -f "pyproject.toml" ] || [ -f "pytest.ini" ]; then | ||
| echo "Running pytest..." | ||
| python -m pytest 2>&1 || echo "❌ FAIL: Tests failed" |
There was a problem hiding this comment.
The pre-deploy pytest check only prints a failure message but does not stop the script. This contradicts the instruction to "Stop and report if any fail." A failed test run should immediately halt the deployment process.
| python -m pytest 2>&1 || echo "❌ FAIL: Tests failed" | |
| python -m pytest 2>&1 || { echo "❌ FAIL: Tests failed. Aborting deployment."; exit 1; } |
| echo -e "\n--- Type Check ---" | ||
| if [ -f "tsconfig.json" ]; then | ||
| echo "Running typecheck..." | ||
| npx tsc --noEmit 2>&1 || bun run typecheck 2>&1 || echo "⚠ Type errors detected" |
There was a problem hiding this comment.
The pre-deploy type check only prints a warning but does not stop the script. This contradicts the instruction to "Stop and report if any fail." Type errors indicate potential bugs, and the deployment should be halted if they are detected.
| npx tsc --noEmit 2>&1 || bun run typecheck 2>&1 || echo "⚠ Type errors detected" | |
| (npx tsc --noEmit || bun run typecheck) 2>&1 || { echo "❌ FAIL: Type errors detected. Aborting deployment."; exit 1; } |
| ls -d */ | while read dir; do | ||
| grep -q "${dir%/}" CLAUDE.md 2>/dev/null || echo "UNDOCUMENTED: $dir" | ||
| done |
There was a problem hiding this comment.
Parsing the output of ls is unreliable and considered bad practice in shell scripting, as it can fail with filenames containing spaces or other special characters. A for loop with a glob pattern is a safer and more robust alternative for iterating over directories.
| ls -d */ | while read dir; do | |
| grep -q "${dir%/}" CLAUDE.md 2>/dev/null || echo "UNDOCUMENTED: $dir" | |
| done | |
| for dir in */; do | |
| if [ -d "$dir" ]; then | |
| grep -qF "${dir%/}" CLAUDE.md 2>/dev/null || echo "UNDOCUMENTED: $dir" | |
| fi | |
| done |
|
|
||
| **AWS CDK:** | ||
| ```bash | ||
| cd infra && npx cdk deploy --all --require-approval broadening |
There was a problem hiding this comment.
The script changes into the infra directory to run cdk deploy but does not change back. This can cause subsequent commands to fail if they expect to be in the project's root directory. Encapsulating the command in a subshell will prevent this issue by isolating the directory change.
| cd infra && npx cdk deploy --all --require-approval broadening | |
| (cd infra && npx cdk deploy --all --require-approval broadening) |
| PROJECTS=$(ls -d "$HOME/code"/*/ 2>/dev/null | while read d; do | ||
| [ -f "$d/CLAUDE.md" ] && echo "$d" | ||
| done) |
There was a problem hiding this comment.
Parsing the output of ls is not robust and can fail if directory names contain spaces or special characters. Using find is a much safer and more reliable way to locate the project directories.
| PROJECTS=$(ls -d "$HOME/code"/*/ 2>/dev/null | while read d; do | |
| [ -f "$d/CLAUDE.md" ] && echo "$d" | |
| done) | |
| PROJECTS=$(find "$HOME/code" -mindepth 1 -maxdepth 1 -type d -exec test -f '{}/CLAUDE.md' \; -print) |
| allowed-tools: Bash(*), View, Task | ||
| description: Load project context and status briefing | ||
| argument-hint: [project name or path] | ||
| model: claude-sonnet-4-5 |
There was a problem hiding this comment.
This command file is missing the extended-thinking: true property in its frontmatter, which is present in the other new command files (deploy.md, doc_sync.md). For consistency and to ensure the AI has adequate time for complex context-loading tasks, this property should be added.
| model: claude-sonnet-4-5 | |
| model: claude-sonnet-4-5 | |
| extended-thinking: true |
| else | ||
| echo "❌ Project not found: $TARGET" | ||
| echo "Available projects in ~/code/:" | ||
| ls -d "$HOME/code"/*/ 2>/dev/null | xargs -I{} basename {} |
There was a problem hiding this comment.
Parsing the output of ls and piping it to xargs is not a robust method and can fail with filenames containing spaces or special characters. Using find with -printf is a safer and more reliable way to list the directory names.
| ls -d "$HOME/code"/*/ 2>/dev/null | xargs -I{} basename {} | |
| find "$HOME/code"/ -mindepth 1 -maxdepth 1 -type d -printf '%f\n' |
Adds plugin-auto-update.sh to SessionStart hooks so the psd-claude-coding-system plugin pulls latest changes from the repo automatically. Uses a daily stamp file to avoid redundant checks — only runs `claude plugin update` once per day. The update runs in a background process so it never blocks session startup. Files changed: - scripts/plugin-auto-update.sh (new): background update with daily throttle - hooks/hooks.json: added auto-update hook to SessionStart array
1 participant
Summary
/project [name]— Loads project context briefing (tech stack, git status, open issues/PRs, TODOs, key commands) to reduce context-switching cost across multiple active apps/deploy [env]— Multi-platform deployment orchestration with pre-checks, auto-detection (AWS CDK, Railway, Cloudflare, Amplify, Cloud Run, GitHub Pages), and post-deploy verification/doc_sync [project|all]— Documentation drift detector that cross-references CLAUDE.md/README against actual codebase for stale paths, outdated deps, missing env vars, and undocumented contentNew files
commands/project.mdcommands/deploy.mdcommands/doc_sync.mdagents/deploy-verifier.mdagents/documentation-auditor.mdTest plan
/psd-claude-coding-system:autocomplete after plugin reload/project kangarooreturns structured briefing/deploy devruns pre-checks and detects platform/doc_sync kangarooidentifies documentation drift🤖 Generated with Claude Code