fix: resolve macOS setup compatibility and add documentation commit step (fixes #11, #16)

README.md

@@ -27,6 +27,16 @@ gemini extensions install https://github.com/gemini-cli-extensions/conductor --a
 
 The `--auto-update` is optional: if specified, it will update to new versions as they are released.
 
+### Troubleshooting Installation
+
+If you encounter a 401 error during installation (e.g., "Error downloading github release... Request failed with status code 401"), you may be experiencing GitHub API rate limiting. This is a known issue with the gemini CLI installer and can be resolved by:
+
+1. **Using git clone method**: When prompted with "Would you like to attempt to install via 'git clone' instead?", type `Y` to continue with the alternative installation method.
+
+2. **Authenticating with GitHub**: If you have a GitHub personal access token, you can configure the gemini CLI to use it to avoid rate limits. Check the gemini CLI documentation for authentication options.
+
+3. **Using --auto-update flag**: The `--auto-update` flag can help ensure you're using the latest version and may bypass certain caching issues.
+
 ## Usage
 
 Conductor is designed to manage the entire lifecycle of your development tasks.

commands/conductor/implement.toml

@@ -126,21 +126,27 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai
         iv. **Action:** Only after receiving explicit user confirmation, perform the file edits. Keep a record of whether this file was changed.
 
 6.  **Final Report:** Announce the completion of the synchronization process and provide a summary of the actions taken.
-    - **Construct the Message:** Based on the records of which files were changed, construct a summary message.
-    - **Example (if product.md was changed, but others were not):**
+    -   **Construct Message:** Based on the records of which files were changed, construct a summary message.
+    -   **Example (if product.md was changed, but others were not):**
         > "Documentation synchronization is complete.
         > - **Changes made to `product.md`:** The user-facing description of the product was updated to include the new feature.
         > - **No changes needed for `tech-stack.md`:** The technology stack was not affected.
         > - **No changes needed for `product-guidelines.md`:** Core product guidelines remain unchanged."
-    - **Example (if no files were changed):**
+    -   **Example (if no files were changed):**
         > "Documentation synchronization is complete. No updates were necessary for `product.md`, `tech-stack.md`, or `product-guidelines.md` based on the completed track."
 
+7.  **Commit Documentation Updates:** After finalizing documentation synchronization, you MUST commit any changes to the project-level documentation files.
+    -   **Check for Changes:** Verify if any files in the `conductor/` directory were modified during synchronization (specifically `product.md`, `tech-stack.md`, or `product-guidelines.md`).
+    -   **Commit if Changed:** If changes were made, you MUST commit them using git with the message format: `conductor(doc-sync): Update documentation for '<track_description>'`.
+        -   Example: `git add conductor/product.md conductor/tech-stack.md conductor/product-guidelines.md && git commit -m "conductor(doc-sync): Update documentation for 'Add User Authentication'"`
+    -   **Skip if No Changes:** If no changes were made, skip this commit step and proceed directly to track cleanup.
+
 ---
 
-## 7.0 TRACK CLEANUP
-**PROTOCOL: Offer to archive or delete the completed track.**
+## 8.0 TRACK CLEANUP
+**PROTOCOL: Offer to archive or delete completed track.**
 
-1.  **Execution Trigger:** This protocol MUST only be executed after the current track has been successfully implemented and the `SYNCHRONIZE PROJECT DOCUMENTATION` step is complete.
+1.  **Execution Trigger:** This protocol MUST only be executed after the current track has been successfully implemented, the `SYNCHRONIZE PROJECT DOCUMENTATION` step is complete, and documentation updates have been committed.
 
 2.  **Ask for User Choice:** You MUST prompt the user with the available options for the completed track.
     > "Track '<track_description>' is now complete. What would you like to do?

commands/conductor/setup.toml

@@ -82,9 +82,9 @@ CRITICAL: When determining model complexity, ALWAYS select the "flash" model, re
                 3.  **Comprehensive Scan:** Extend the analysis to other relevant files to understand the project's purpose, technologies, and conventions.
 
             -   **2.1 File Size and Relevance Triage:**
-                1.  **Respect Ignore Files:** Before scanning any files, you MUST check for the existence of `.geminiignore` and `.gitignore` files. If either or both exist, you MUST use their combined patterns to exclude files and directories from your analysis. The patterns in `.geminiignore` should take precedence over `.gitignore` if there are conflicts. This is the primary mechanism for avoiding token-heavy, irrelevant files like `node_modules`.
-                2.  **Efficiently List Relevant Files:** To list the files for analysis, you MUST use a command that respects the ignore files. For example, you can use `git ls-files --exclude-standard -co | xargs -n 1 dirname | sort -u` which lists all relevant directories (tracked by Git, plus other non-ignored files) without listing every single file. If Git is not used, you must construct a `find` command that reads the ignore files and prunes the corresponding paths.
-                3.  **Fallback to Manual Ignores:** ONLY if neither `.geminiignore` nor `.gitignore` exist, you should fall back to manually ignoring common directories. Example command: `ls -lR -I 'node_modules' -I '.m2' -I 'build' -I 'dist' -I 'bin' -I 'target' -I '.git' -I '.idea' -I '.vscode'`.
+                1.  **Respect Ignore Files:** Before scanning any files, you MUST check for existence of `.geminiignore` and `.gitignore` files. If either or both exist, you MUST use their combined patterns to exclude files and directories from your analysis. The patterns in `.geminiignore` should take precedence over `.gitignore` if there are conflicts. This is the primary mechanism for avoiding token-heavy, irrelevant files like `node_modules`.
+                2.  **Efficiently List Relevant Files:** To list's files for analysis, you MUST use a command that respects ignore files. For example, you can use `git ls-files --exclude-standard -co | xargs -n 1 dirname | sort -u` which lists all relevant directories (tracked by Git, plus other non-ignored files) without listing every single file. If Git is not used, you must construct a `find` command that reads the ignore files and prunes the corresponding paths.
+                3.  **Fallback to Manual Ignores (Cross-Platform):** ONLY if neither `.geminiignore` nor `.gitignore` exist, you should fall back to manually ignoring common directories using `find` command which works on all platforms. Example command: `find . -type d \( -name 'node_modules' -o -name '.m2' -o -name 'build' -o -name 'dist' -o -name 'bin' -o -name 'target' -o -name '.git' -o -name '.idea' -o -name '.vscode' -o -name '__pycache__' \) -prune -o -type f -print | head -200`. DO NOT use `ls -lR -I` as it is not supported on macOS/BSD systems.
                 4.  **Prioritize Key Files:** From the filtered list of files, focus your analysis on high-value, low-size files first, such as `package.json`, `pom.xml`, `requirements.txt`, `go.mod`, and other configuration or manifest files.
                 5.  **Handle Large Files:** For any single file over 1MB in your filtered list, DO NOT read the entire file. Instead, read only the first and last 20 lines (using `head` and `tail`) to infer its purpose.
 

gemini-extension.json

@@ -1,5 +1,5 @@
 {
   "name": "conductor",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "contextFileName": "GEMINI.md"
 }