├── gemini-extension.json
├── GEMINI.md
├── templates
    ├── code_styleguides
    │   ├── general.md
    │   ├── python.md
    │   ├── html-css.md
    │   ├── javascript.md
    │   ├── typescript.md
    │   └── go.md
    └── workflow.md
├── CONTRIBUTING.md
├── .github
    └── workflows
    │   └── package-and-upload-assets.yml
├── commands
    └── conductor
    │   ├── status.toml
    │   ├── revert.toml
    │   ├── newTrack.toml
    │   ├── implement.toml
    │   └── setup.toml
├── .gitignore
├── README.md
└── LICENSE


/gemini-extension.json:
--------------------------------------------------------------------------------
1 | {
2 |   "name": "conductor",
3 |   "version": "0.1.0",
4 |   "contextFileName": "GEMINI.md"
5 | }


--------------------------------------------------------------------------------
/GEMINI.md:
--------------------------------------------------------------------------------
1 | # Conductor Context
2 | 
3 | If a user mentions a "plan" or asks about the plan, and they have used the conductor extension in the current session, they are likely referring to the `conductor/tracks.md` file or one of the track plans (`conductor/tracks/<track_id>/plan.md`).
4 | 


--------------------------------------------------------------------------------
/templates/code_styleguides/general.md:
--------------------------------------------------------------------------------
 1 | # General Code Style Principles
 2 | 
 3 | This document outlines general coding principles that apply across all languages and frameworks used in this project.
 4 | 
 5 | ## Readability
 6 | - Code should be easy to read and understand by humans.
 7 | - Avoid overly clever or obscure constructs.
 8 | 
 9 | ## Consistency
10 | - Follow existing patterns in the codebase.
11 | - Maintain consistent formatting, naming, and structure.
12 | 
13 | ## Simplicity
14 | - Prefer simple solutions over complex ones.
15 | - Break down complex problems into smaller, manageable parts.
16 | 
17 | ## Maintainability
18 | - Write code that is easy to modify and extend.
19 | - Minimize dependencies and coupling.
20 | 
21 | ## Documentation
22 | - Document *why* something is done, not just *what*.
23 | - Keep documentation up-to-date with code changes.
24 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | # How to contribute
 2 | 
 3 | We'd love to accept your patches and contributions to this project.
 4 | 
 5 | ## Before you begin
 6 | 
 7 | ### Sign our Contributor License Agreement
 8 | 
 9 | Contributions to this project must be accompanied by a
10 | [Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
11 | You (or your employer) retain the copyright to your contribution; this simply
12 | gives us permission to use and redistribute your contributions as part of the
13 | project.
14 | 
15 | If you or your current employer have already signed the Google CLA (even if it
16 | was for a different project), you probably don't need to do it again.
17 | 
18 | Visit <https://cla.developers.google.com/> to see your current agreements or to
19 | sign a new one.
20 | 
21 | ### Review our community guidelines
22 | 
23 | This project follows
24 | [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
25 | 
26 | ## Contribution process
27 | 
28 | ### Code reviews
29 | 
30 | All submissions, including submissions by project members, require review. We
31 | use GitHub pull requests for this purpose. Consult
32 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
33 | information on using pull requests.


--------------------------------------------------------------------------------
/.github/workflows/package-and-upload-assets.yml:
--------------------------------------------------------------------------------
 1 | name: Package and Upload Release Assets
 2 | 
 3 | on:
 4 |   release:
 5 |     types: [created]
 6 | 
 7 |   # This allows you to run the workflow manually from the Actions tab
 8 |   workflow_dispatch:
 9 |     inputs:
10 |       tag_name:
11 |         description: 'The tag of the release to upload assets to'
12 |         required: true
13 |         type: string
14 | 
15 | permissions:
16 |   # This permission is required for the action to create a GitHub Release
17 |   contents: write
18 | 
19 | jobs:
20 |   package-and-upload:
21 |     runs-on: ubuntu-latest
22 |     steps:
23 |       # 1. Checks out your repository's code
24 |       - name: Checkout code
25 |         uses: actions/checkout@v4
26 | 
27 |       # 2. Create TAR archive
28 |       - name: Create TAR archive
29 |         run: tar -czvf ../conductor-release.tar.gz --exclude='.git' --exclude='.github' . && mv ../conductor-release.tar.gz .
30 | 
31 |       # 3. Upload the TAR archive as a release asset
32 |       - name: Upload archive to GitHub Release
33 |         env:
34 |           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
35 |         run: |
36 |           gh release upload \
37 |             ${{ github.event.release.tag_name || inputs.tag_name }} \
38 |             conductor-release.tar.gz


--------------------------------------------------------------------------------
/templates/code_styleguides/python.md:
--------------------------------------------------------------------------------
 1 | # Google Python Style Guide Summary
 2 | 
 3 | This document summarizes key rules and best practices from the Google Python Style Guide.
 4 | 
 5 | ## 1. Python Language Rules
 6 | - **Linting:** Run `pylint` on your code to catch bugs and style issues.
 7 | - **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule.
 8 | - **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses.
 9 | - **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`.
10 | - **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable.
11 | - **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values.
12 | - **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`.
13 | - **Type Annotations:** Strongly encouraged for all public APIs.
14 | 
15 | ## 2. Python Style Rules
16 | - **Line Length:** Maximum 80 characters.
17 | - **Indentation:** 4 spaces per indentation level. Never use tabs.
18 | - **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions.
19 | - **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces.
20 | - **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring.
21 |   - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections.
22 | - **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes.
23 | - **`TODO` Comments:** Use `TODO(username): Fix this.` format.
24 | - **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports.
25 | 
26 | ## 3. Naming
27 | - **General:** `snake_case` for modules, functions, methods, and variables.
28 | - **Classes:** `PascalCase`.
29 | - **Constants:** `ALL_CAPS_WITH_UNDERSCORES`.
30 | - **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members.
31 | 
32 | ## 4. Main
33 | - All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block.
34 | 
35 | **BE CONSISTENT.** When editing code, match the existing style.
36 | 
37 | *Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)*


--------------------------------------------------------------------------------
/templates/code_styleguides/html-css.md:
--------------------------------------------------------------------------------
 1 | # Google HTML/CSS Style Guide Summary
 2 | 
 3 | This document summarizes key rules and best practices from the Google HTML/CSS Style Guide.
 4 | 
 5 | ## 1. General Rules
 6 | - **Protocol:** Use HTTPS for all embedded resources.
 7 | - **Indentation:** Indent by 2 spaces. Do not use tabs.
 8 | - **Capitalization:** Use only lowercase for all code (element names, attributes, selectors, properties).
 9 | - **Trailing Whitespace:** Remove all trailing whitespace.
10 | - **Encoding:** Use UTF-8 (without a BOM). Specify `<meta charset="utf-8">` in HTML.
11 | 
12 | ## 2. HTML Style Rules
13 | - **Document Type:** Use `<!doctype html>`.
14 | - **HTML Validity:** Use valid HTML.
15 | - **Semantics:** Use HTML elements according to their intended purpose (e.g., use `<p>` for paragraphs, not for spacing).
16 | - **Multimedia Fallback:** Provide `alt` text for images and transcripts/captions for audio/video.
17 | - **Separation of Concerns:** Strictly separate structure (HTML), presentation (CSS), and behavior (JavaScript). Link to CSS and JS from external files.
18 | - **`type` Attributes:** Omit `type` attributes for stylesheets (`<link>`) and scripts (`<script>`).
19 | 
20 | ## 3. HTML Formatting Rules
21 | - **General:** Use a new line for every block, list, or table element, and indent its children.
22 | - **Quotation Marks:** Use double quotation marks (`""`) for attribute values.
23 | 
24 | ## 4. CSS Style Rules
25 | - **CSS Validity:** Use valid CSS.
26 | - **Class Naming:** Use meaningful, generic names. Separate words with a hyphen (`-`).
27 |   - **Good:** `.video-player`, `.site-navigation`
28 |   - **Bad:** `.vid`, `.red-text`
29 | - **ID Selectors:** Avoid using ID selectors for styling. Prefer class selectors.
30 | - **Shorthand Properties:** Use shorthand properties where possible (e.g., `padding`, `font`).
31 | - **`0` and Units:** Omit units for `0` values (e.g., `margin: 0;`).
32 | - **Leading `0`s:** Always include leading `0`s for decimal values (e.g., `font-size: 0.8em;`).
33 | - **Hexadecimal Notation:** Use 3-character hex notation where possible (e.g., `#fff`).
34 | - **`!important`:** Avoid using `!important`.
35 | 
36 | ## 5. CSS Formatting Rules
37 | - **Declaration Order:** Alphabetize declarations within a rule.
38 | - **Indentation:** Indent all block content.
39 | - **Semicolons:** Use a semicolon after every declaration.
40 | - **Spacing:**
41 |   - Use a space after a property name's colon (`font-weight: bold;`).
42 |   - Use a space between the last selector and the opening brace (`.foo {`).
43 |   - Start a new line for each selector and declaration.
44 | - **Rule Separation:** Separate rules with a new line.
45 | - **Quotation Marks:** Use single quotes (`''`) for attribute selectors and property values (e.g., `[type='text']`).
46 | 
47 | **BE CONSISTENT.** When editing code, match the existing style.
48 | 
49 | *Source: [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)*


--------------------------------------------------------------------------------
/templates/code_styleguides/javascript.md:
--------------------------------------------------------------------------------
 1 | # Google JavaScript Style Guide Summary
 2 | 
 3 | This document summarizes key rules and best practices from the Google JavaScript Style Guide.
 4 | 
 5 | ## 1. Source File Basics
 6 | - **File Naming:** All lowercase, with underscores (`_`) or dashes (`-`). Extension must be `.js`.
 7 | - **File Encoding:** UTF-8.
 8 | - **Whitespace:** Use only ASCII horizontal spaces (0x20). Tabs are forbidden for indentation.
 9 | 
10 | ## 2. Source File Structure
11 | - New files should be ES modules (`import`/`export`).
12 | - **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
13 | - **Imports:** Do not use line-wrapped imports. The `.js` extension in import paths is mandatory.
14 | 
15 | ## 3. Formatting
16 | - **Braces:** Required for all control structures (`if`, `for`, `while`, etc.), even single-line blocks. Use K&R style ("Egyptian brackets").
17 | - **Indentation:** +2 spaces for each new block.
18 | - **Semicolons:** Every statement must be terminated with a semicolon.
19 | - **Column Limit:** 80 characters.
20 | - **Line-wrapping:** Indent continuation lines at least +4 spaces.
21 | - **Whitespace:** Use single blank lines between methods. No trailing whitespace.
22 | 
23 | ## 4. Language Features
24 | - **Variable Declarations:** Use `const` by default, `let` if reassignment is needed. **`var` is forbidden.**
25 | - **Array Literals:** Use trailing commas. Do not use the `Array` constructor.
26 | - **Object Literals:** Use trailing commas and shorthand properties. Do not use the `Object` constructor.
27 | - **Classes:** Do not use JavaScript getter/setter properties (`get name()`). Provide ordinary methods instead.
28 | - **Functions:** Prefer arrow functions for nested functions to preserve `this` context.
29 | - **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for multi-line strings or complex interpolation.
30 | - **Control Structures:** Prefer `for-of` loops. `for-in` loops should only be used on dict-style objects.
31 | - **`this`:** Only use `this` in class constructors, methods, or in arrow functions defined within them.
32 | - **Equality Checks:** Always use identity operators (`===` / `!==`).
33 | 
34 | ## 5. Disallowed Features
35 | - `with` keyword.
36 | - `eval()` or `Function(...string)`.
37 | - Automatic Semicolon Insertion.
38 | - Modifying builtin objects (`Array.prototype.foo = ...`).
39 | 
40 | ## 6. Naming
41 | - **Classes:** `UpperCamelCase`.
42 | - **Methods & Functions:** `lowerCamelCase`.
43 | - **Constants:** `CONSTANT_CASE` (all uppercase with underscores).
44 | - **Non-constant Fields & Variables:** `lowerCamelCase`.
45 | 
46 | ## 7. JSDoc
47 | - JSDoc is used on all classes, fields, and methods.
48 | - Use `@param`, `@return`, `@override`, `@deprecated`.
49 | - Type annotations are enclosed in braces (e.g., `/** @param {string} userName */`).
50 | 
51 | *Source: [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)*


--------------------------------------------------------------------------------
/templates/code_styleguides/typescript.md:
--------------------------------------------------------------------------------
 1 | # Google TypeScript Style Guide Summary
 2 | 
 3 | This document summarizes key rules and best practices from the Google TypeScript Style Guide, which is enforced by the `gts` tool.
 4 | 
 5 | ## 1. Language Features
 6 | - **Variable Declarations:** Always use `const` or `let`. **`var` is forbidden.** Use `const` by default.
 7 | - **Modules:** Use ES6 modules (`import`/`export`). **Do not use `namespace`.**
 8 | - **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
 9 | - **Classes:**
10 |   - **Do not use `#private` fields.** Use TypeScript's `private` visibility modifier.
11 |   - Mark properties never reassigned outside the constructor with `readonly`.
12 |   - **Never use the `public` modifier** (it's the default). Restrict visibility with `private` or `protected` where possible.
13 | - **Functions:** Prefer function declarations for named functions. Use arrow functions for anonymous functions/callbacks.
14 | - **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for interpolation and multi-line strings.
15 | - **Equality Checks:** Always use triple equals (`===`) and not equals (`!==`).
16 | - **Type Assertions:** **Avoid type assertions (`x as SomeType`) and non-nullability assertions (`y!`)**. If you must use them, provide a clear justification.
17 | 
18 | ## 2. Disallowed Features
19 | - **`any` Type:** **Avoid `any`**. Prefer `unknown` or a more specific type.
20 | - **Wrapper Objects:** Do not instantiate `String`, `Boolean`, or `Number` wrapper classes.
21 | - **Automatic Semicolon Insertion (ASI):** Do not rely on it. **Explicitly end all statements with a semicolon.**
22 | - **`const enum`:** Do not use `const enum`. Use plain `enum` instead.
23 | - **`eval()` and `Function(...string)`:** Forbidden.
24 | 
25 | ## 3. Naming
26 | - **`UpperCamelCase`:** For classes, interfaces, types, enums, and decorators.
27 | - **`lowerCamelCase`:** For variables, parameters, functions, methods, and properties.
28 | - **`CONSTANT_CASE`:** For global constant values, including enum values.
29 | - **`_` Prefix/Suffix:** **Do not use `_` as a prefix or suffix** for identifiers, including for private properties.
30 | 
31 | ## 4. Type System
32 | - **Type Inference:** Rely on type inference for simple, obvious types. Be explicit for complex types.
33 | - **`undefined` and `null`:** Both are supported. Be consistent within your project.
34 | - **Optional vs. `|undefined`:** Prefer optional parameters and fields (`?`) over adding `|undefined` to the type.
35 | - **`Array<T>` Type:** Use `T[]` for simple types. Use `Array<T>` for more complex union types (e.g., `Array<string | number>`).
36 | - **`{}` Type:** **Do not use `{}`**. Prefer `unknown`, `Record<string, unknown>`, or `object`.
37 | 
38 | ## 5. Comments and Documentation
39 | - **JSDoc:** Use `/** JSDoc */` for documentation, `//` for implementation comments.
40 | - **Redundancy:** **Do not declare types in `@param` or `@return` blocks** (e.g., `/** @param {string} user */`). This is redundant in TypeScript.
41 | - **Add Information:** Comments must add information, not just restate the code.
42 | 
43 | *Source: [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)*


--------------------------------------------------------------------------------
/templates/code_styleguides/go.md:
--------------------------------------------------------------------------------
 1 | # Effective Go Style Guide Summary
 2 | 
 3 | This document summarizes key rules and best practices from the official "Effective Go" guide for writing idiomatic Go code.
 4 | 
 5 | ## 1. Formatting
 6 | - **`gofmt`:** All Go code **must** be formatted with `gofmt` (or `go fmt`). This is a non-negotiable, automated standard.
 7 | - **Indentation:** Use tabs for indentation (`gofmt` handles this).
 8 | - **Line Length:** Go has no strict line length limit. Let `gofmt` handle line wrapping.
 9 | 
10 | ## 2. Naming
11 | - **`MixedCaps`:** Use `MixedCaps` or `mixedCaps` for multi-word names. Do not use underscores.
12 | - **Exported vs. Unexported:** Names starting with an uppercase letter are exported (public). Names starting with a lowercase letter are not exported (private).
13 | - **Package Names:** Short, concise, single-word, lowercase names.
14 | - **Getters:** Do not name getters with a `Get` prefix. A getter for a field named `owner` should be named `Owner()`.
15 | - **Interface Names:** One-method interfaces are named by the method name plus an `-er` suffix (e.g., `Reader`, `Writer`).
16 | 
17 | ## 3. Control Structures
18 | - **`if`:** No parentheses around the condition. Braces are mandatory. Can include an initialization statement (e.g., `if err := file.Chmod(0664); err != nil`).
19 | - **`for`:** Go's only looping construct. Unifies `for` and `while`. Use `for...range` to iterate over slices, maps, strings, and channels.
20 | - **`switch`:** More general than in C. Cases do not fall through by default (use `fallthrough` explicitly). Can be used without an expression to function as a cleaner `if-else-if` chain.
21 | 
22 | ## 4. Functions
23 | - **Multiple Returns:** Functions can return multiple values. This is the standard way to return a result and an error (e.g., `value, err`).
24 | - **Named Result Parameters:** Return parameters can be named. This can make code clearer and more concise.
25 | - **`defer`:** Schedules a function call to be run immediately before the function executing `defer` returns. Use it for cleanup tasks like closing files.
26 | 
27 | ## 5. Data
28 | - **`new` vs. `make`:**
29 |   - `new(T)`: Allocates memory for a new item of type `T`, zeroes it, and returns a pointer (`*T`).
30 |   - `make(T, ...)`: Creates and initializes slices, maps, and channels only. Returns an initialized value of type `T` (not a pointer).
31 | - **Slices:** The preferred way to work with sequences. They are more flexible than arrays.
32 | - **Maps:** Use the "comma ok" idiom to check for the existence of a key: `value, ok := myMap[key]`.
33 | 
34 | ## 6. Interfaces
35 | - **Implicit Implementation:** A type implements an interface by implementing its methods. No `implements` keyword is needed.
36 | - **Small Interfaces:** Prefer many small interfaces over one large one. The standard library is full of single-method interfaces (e.g., `io.Reader`).
37 | 
38 | ## 7. Concurrency
39 | - **Share Memory By Communicating:** This is the core philosophy. Do not communicate by sharing memory; instead, share memory by communicating.
40 | - **Goroutines:** Lightweight, concurrently executing functions. Start one with the `go` keyword.
41 | - **Channels:** Typed conduits for communication between goroutines. Use `make` to create them.
42 | 
43 | ## 8. Errors
44 | - **`error` type:** The built-in `error` interface is the standard way to handle errors.
45 | - **Explicit Error Handling:** Do not discard errors with the blank identifier (`_`). Check for errors explicitly.
46 | - **`panic`:** Reserved for truly exceptional, unrecoverable situations. Generally, libraries should not panic.
47 | 
48 | *Source: [Effective Go](https://go.dev/doc/effective_go)*


--------------------------------------------------------------------------------
/commands/conductor/status.toml:
--------------------------------------------------------------------------------
 1 | description = "Displays the current progress of the project"
 2 | prompt = """
 3 | ## 1.0 SYSTEM DIRECTIVE
 4 | You are an AI agent. Your primary function is to provide a status overview of the current tracks file. This involves reading the `conductor/tracks.md` file, parsing its content, and summarizing the progress of tasks.
 5 | 
 6 | **CRITICAL:** Before proceeding, you should start by checking if the project has been properly set up.
 7 | 1.  **Verify Tracks File:** Check if the file `conductor/tracks.md` exists. If it does not, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md."
 8 | 2.  **Verify Track Exists:** Check if the file `conductor/tracks.md` is not empty. If it is empty, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md."
 9 | 
10 | CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
11 | 
12 | ---
13 | 
14 | 
15 | ## 1.1 SETUP CHECK
16 | **PROTOCOL: Verify that the Conductor environment is properly set up.**
17 | 
18 | 1.  **Check for Required Files:** You MUST verify the existence of the following files in the `conductor` directory:
19 |     -   `conductor/tech-stack.md`
20 |     -   `conductor/workflow.md`
21 |     -   `conductor/product.md`
22 | 
23 | 2.  **Handle Missing Files:**
24 |     -   If ANY of these files are missing, you MUST halt the operation immediately.
25 |     -   Announce: "Conductor is not set up. Please run `/conductor:setup` to set up the environment."
26 |     -   Do NOT proceed to Status Overview Protocol.
27 | 
28 | ---
29 | 
30 | ## 2.0 STATUS OVERVIEW PROTOCOL
31 | **PROTOCOL: Follow this sequence to provide a status overview.**
32 | 
33 | ### 2.1 Read Project Plan
34 | 1.  **Locate and Read:** Read the content of the `conductor/tracks.md` file.
35 | 2.  **Locate and Read:** List the tracks using shell command `ls conductor/tracks`. For each of the tracks, read the corresponding `conductor/<track_id>/plan.md` file.
36 | 
37 | ### 2.2 Parse and Summarize Plan
38 | 1.  **Parse Content:**
39 |     -   Identify major project phases/sections (e.g., top-level markdown headings).
40 |     -   Identify individual tasks and their current status (e.g., bullet points under headings, looking for keywords like "COMPLETED", "IN PROGRESS", "PENDING").
41 | 2.  **Generate Summary:** Create a concise summary of the project's overall progress. This should include:
42 |     -   The total number of major phases.
43 |     -   The total number of tasks.
44 |     -   The number of tasks completed, in progress, and pending.
45 | 
46 | ### 2.3 Present Status Overview
47 | 1.  **Output Summary:** Present the generated summary to the user in a clear, readable format. The status report must include:
48 |     -   **Current Date/Time:** The current timestamp.
49 |     -   **Project Status:** A high-level summary of progress (e.g., "On Track", "Behind Schedule", "Blocked").
50 |     -   **Current Phase and Task:** The specific phase and task currently marked as "IN PROGRESS".
51 |     -   **Next Action Needed:** The next task listed as "PENDING".
52 |     -   **Blockers:** Any items explicitly marked as blockers in the plan.
53 |     -   **Phases (total):** The total number of major phases.
54 |     -   **Tasks (total):** The total number of tasks.
55 |     -   **Progress:** The overall progress of the plan, presented as tasks_completed/tasks_total (percentage_completed%).
56 | 
57 | """


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Byte-compiled / optimized / DLL files
  2 | __pycache__/
  3 | *.py[codz]
  4 | *$py.class
  5 | 
  6 | # C extensions
  7 | *.so
  8 | 
  9 | # Distribution / packaging
 10 | .Python
 11 | build/
 12 | develop-eggs/
 13 | dist/
 14 | downloads/
 15 | eggs/
 16 | .eggs/
 17 | lib/
 18 | lib64/
 19 | parts/
 20 | sdist/
 21 | var/
 22 | wheels/
 23 | share/python-wheels/
 24 | *.egg-info/
 25 | .installed.cfg
 26 | *.egg
 27 | MANIFEST
 28 | 
 29 | # PyInstaller
 30 | #  Usually these files are written by a python script from a template
 31 | #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 32 | *.manifest
 33 | *.spec
 34 | 
 35 | # Installer logs
 36 | pip-log.txt
 37 | pip-delete-this-directory.txt
 38 | 
 39 | # Unit test / coverage reports
 40 | htmlcov/
 41 | .tox/
 42 | .nox/
 43 | .coverage
 44 | .coverage.*
 45 | .cache
 46 | nosetests.xml
 47 | coverage.xml
 48 | *.cover
 49 | *.py.cover
 50 | .hypothesis/
 51 | .pytest_cache/
 52 | cover/
 53 | 
 54 | # Translations
 55 | *.mo
 56 | *.pot
 57 | 
 58 | # Django stuff:
 59 | *.log
 60 | local_settings.py
 61 | db.sqlite3
 62 | db.sqlite3-journal
 63 | 
 64 | # Flask stuff:
 65 | instance/
 66 | .webassets-cache
 67 | 
 68 | # Scrapy stuff:
 69 | .scrapy
 70 | 
 71 | # Sphinx documentation
 72 | docs/_build/
 73 | 
 74 | # PyBuilder
 75 | .pybuilder/
 76 | target/
 77 | 
 78 | # Jupyter Notebook
 79 | .ipynb_checkpoints
 80 | 
 81 | # IPython
 82 | profile_default/
 83 | ipython_config.py
 84 | 
 85 | # pyenv
 86 | #   For a library or package, you might want to ignore these files since the code is
 87 | #   intended to run in multiple environments; otherwise, check them in:
 88 | # .python-version
 89 | 
 90 | # pipenv
 91 | #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
 92 | #   However, in case of collaboration, if having platform-specific dependencies or dependencies
 93 | #   having no cross-platform support, pipenv may install dependencies that don't work, or not
 94 | #   install all needed dependencies.
 95 | #Pipfile.lock
 96 | 
 97 | # UV
 98 | #   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
 99 | #   This is especially recommended for binary packages to ensure reproducibility, and is more
100 | #   commonly ignored for libraries.
101 | #uv.lock
102 | 
103 | # poetry
104 | #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105 | #   This is especially recommended for binary packages to ensure reproducibility, and is more
106 | #   commonly ignored for libraries.
107 | #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108 | #poetry.lock
109 | #poetry.toml
110 | 
111 | # pdm
112 | #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113 | #   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
114 | #   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
115 | #pdm.lock
116 | #pdm.toml
117 | .pdm-python
118 | .pdm-build/
119 | 
120 | # pixi
121 | #   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
122 | #pixi.lock
123 | #   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
124 | #   in the .venv directory. It is recommended not to include this directory in version control.
125 | .pixi
126 | 
127 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
128 | __pypackages__/
129 | 
130 | # Celery stuff
131 | celerybeat-schedule
132 | celerybeat.pid
133 | 
134 | # SageMath parsed files
135 | *.sage.py
136 | 
137 | # Environments
138 | .env
139 | .envrc
140 | .venv
141 | env/
142 | venv/
143 | ENV/
144 | env.bak/
145 | venv.bak/
146 | 
147 | # Spyder project settings
148 | .spyderproject
149 | .spyproject
150 | 
151 | # Rope project settings
152 | .ropeproject
153 | 
154 | # mkdocs documentation
155 | /site
156 | 
157 | # mypy
158 | .mypy_cache/
159 | .dmypy.json
160 | dmypy.json
161 | 
162 | # Pyre type checker
163 | .pyre/
164 | 
165 | # pytype static type analyzer
166 | .pytype/
167 | 
168 | # Cython debug symbols
169 | cython_debug/
170 | 
171 | # PyCharm
172 | #  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
173 | #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
174 | #  and can be added to the global gitignore or merged into this file.  For a more nuclear
175 | #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
176 | #.idea/
177 | 
178 | # Visual Studio Code
179 | #  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
180 | #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
181 | #  and can be added to the global gitignore or merged into this file. However, if you prefer,
182 | #  you could uncomment the following to ignore the entire vscode folder
183 | # .vscode/
184 | 
185 | # Ruff stuff:
186 | .ruff_cache/
187 | 
188 | # PyPI configuration file
189 | .pypirc
190 | 
191 | # Cursor
192 | #  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
193 | #  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
194 | #  refer to https://docs.cursor.com/context/ignore-files
195 | .cursorignore
196 | .cursorindexingignore
197 | 
198 | # Marimo
199 | marimo/_static/
200 | marimo/_lsp/
201 | __marimo__/
202 | 
203 | .DS_Store
204 | 
205 | # Genkit
206 | .genkit/
207 | 
208 | # Conductor
209 | tmp/
210 | 
211 | /.gemini/tmp/
212 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Conductor Extension for Gemini CLI
  2 | 
  3 | **Measure twice, code once.**
  4 | 
  5 | Conductor is a Gemini CLI extension that enables **Context-Driven Development**. It turns the Gemini CLI into a proactive project manager that follows a strict protocol to specify, plan, and implement software features and bug fixes.
  6 | 
  7 | Instead of just writing code, Conductor ensures a consistent, high-quality lifecycle for every task: **Context -> Spec & Plan -> Implement**.
  8 | 
  9 | The philosophy behind Conductor is simple: control your code. By treating context as a managed artifact alongside your code, you transform your repository into a single source of truth that drives every agent interaction with deep, persistent project awareness.
 10 | 
 11 | ## Features
 12 | 
 13 | - **Plan before you build**: Create specs and plans that guide the agent for new and existing codebases.
 14 | - **Maintain context**: Ensure AI follows style guides, tech stack choices, and product goals.
 15 | - **Iterate safely**: Review plans before code is written, keeping you firmly in the loop.
 16 | - **Work as a team**: Set project-level context for your product, tech stack, and workflow preferences that become a shared foundation for your team.
 17 | - **Build on existing projects**: Intelligent initialization for both new (Greenfield) and existing (Brownfield) projects.
 18 | - **Smart revert**: A git-aware revert command that understands logical units of work (tracks, phases, tasks) rather than just commit hashes.
 19 | 
 20 | ## Installation
 21 | 
 22 | Install the Conductor extension by running the following command from your terminal:
 23 | 
 24 | ```bash
 25 | gemini extensions install https://github.com/gemini-cli-extensions/conductor --auto-update
 26 | ```
 27 | 
 28 | The `--auto-update` is optional: if specified, it will update to new versions as they are released.
 29 | 
 30 | ## Usage
 31 | 
 32 | Conductor is designed to manage the entire lifecycle of your development tasks.
 33 | 
 34 | **Note on Token Consumption:** Conductor's context-driven approach involves reading and analyzing your project's context, specifications, and plans. This can lead to increased token consumption, especially in larger projects or during extensive planning and implementation phases. You can check the token consumption in the current session by running `/stats model`.
 35 | 
 36 | ### 1. Set Up the Project (Run Once)
 37 | 
 38 | When you run `/conductor:setup`, Conductor helps you define the core components of your project context. This context is then used for building new components or features by you or anyone on your team.
 39 | 
 40 | - **Product**: Define project context (e.g. users, product goals, high-level features).
 41 | - **Product guidelines**: Define standards (e.g. prose style, brand messaging, visual identity).
 42 | - **Tech stack**: Configure technical preferences (e.g. language, database, frameworks).
 43 | - **Workflow**: Set team preferences (e.g. TDD, commit strategy). Uses [workflow.md](templates/workflow.md) as a customizable template.
 44 | 
 45 | **Generated Artifacts:**
 46 | - `conductor/product.md`
 47 | - `conductor/product-guidelines.md`
 48 | - `conductor/tech-stack.md`
 49 | - `conductor/workflow.md`
 50 | - `conductor/code_styleguides/`
 51 | - `conductor/tracks.md`
 52 | 
 53 | ```bash
 54 | /conductor:setup
 55 | ```
 56 | 
 57 | ### 2. Start a New Track (Feature or Bug)
 58 | 
 59 | When you’re ready to take on a new feature or bug fix, run `/conductor:newTrack`. This initializes a **track** — a high-level unit of work. Conductor helps you generate two critical artifacts:
 60 | 
 61 | - **Specs**: The detailed requirements for the specific job. What are we building and why?
 62 | - **Plan**: An actionable to-do list containing phases, tasks, and sub-tasks.
 63 | 
 64 | **Generated Artifacts:**
 65 | - `conductor/tracks/<track_id>/spec.md`
 66 | - `conductor/tracks/<track_id>/plan.md`
 67 | - `conductor/tracks/<track_id>/metadata.json`
 68 | 
 69 | ```bash
 70 | /conductor:newTrack
 71 | # OR with a description
 72 | /conductor:newTrack "Add a dark mode toggle to the settings page"
 73 | ```
 74 | 
 75 | ### 3. Implement the Track
 76 | 
 77 | Once you approve the plan, run `/conductor:implement`. Your coding agent then works through the `plan.md` file, checking off tasks as it completes them.
 78 | 
 79 | **Updated Artifacts:**
 80 | - `conductor/tracks.md` (Status updates)
 81 | - `conductor/tracks/<track_id>/plan.md` (Status updates)
 82 | - Project context files (Synchronized on completion)
 83 | 
 84 | ```bash
 85 | /conductor:implement
 86 | ```
 87 | 
 88 | Conductor will:
 89 | 1.  Select the next pending task.
 90 | 2.  Follow the defined workflow (e.g., TDD: Write Test -> Fail -> Implement -> Pass).
 91 | 3.  Update the status in the plan as it progresses.
 92 | 4.  **Verify Progress**: Guide you through a manual verification step at the end of each phase to ensure everything works as expected.
 93 | 
 94 | During implementation, you can also:
 95 | 
 96 | - **Check status**: Get a high-level overview of your project's progress.
 97 |   ```bash
 98 |   /conductor:status
 99 |   ```
100 | - **Revert work**: Undo a feature or a specific task if needed.
101 |   ```bash
102 |   /conductor:revert
103 |   ```
104 | 
105 | ## Commands Reference
106 | 
107 | | Command | Description | Artifacts |
108 | | :--- | :--- | :--- |
109 | | `/conductor:setup` | Scaffolds the project and sets up the Conductor environment. Run this once per project. | `conductor/product.md`<br>`conductor/tech-stack.md`<br>`conductor/workflow.md`<br>`conductor/tracks.md` |
110 | | `/conductor:newTrack` | Starts a new feature or bug track. Generates `spec.md` and `plan.md`. | `conductor/tracks/<id>/spec.md`<br>`conductor/tracks/<id>/plan.md`<br>`conductor/tracks.md` |
111 | | `/conductor:implement` | Executes the tasks defined in the current track's plan. | `conductor/tracks.md`<br>`conductor/tracks/<id>/plan.md` |
112 | | `/conductor:status` | Displays the current progress of the tracks file and active tracks. | Reads `conductor/tracks.md` |
113 | | `/conductor:revert` | Reverts a track, phase, or task by analyzing git history. | Reverts git history |
114 | 
115 | ## Resources
116 | 
117 | - [Gemini CLI extensions](https://geminicli.com/docs/extensions/): Documentation about using extensions in Gemini CLI
118 | - [GitHub issues](https://github.com/gemini-cli-extensions/conductor/issues): Report bugs or request features
119 | 
120 | ## Legal
121 | 
122 | - License: [Apache License 2.0](LICENSE)
123 | 


--------------------------------------------------------------------------------
/commands/conductor/revert.toml:
--------------------------------------------------------------------------------
  1 | description = "Reverts previous work"
  2 | prompt = """
  3 | ## 1.0 SYSTEM DIRECTIVE
  4 | You are an AI agent for the Conductor framework. Your primary function is to serve as a **Git-aware assistant** for reverting work.
  5 | 
  6 | **Your defined scope is to revert the logical units of work tracked by Conductor (Tracks, Phases, and Tasks).** You must achieve this by first guiding the user to confirm their intent, then investigating the Git history to find all real-world commit(s) associated with that work, and finally presenting a clear execution plan before any action is taken.
  7 | 
  8 | Your workflow MUST anticipate and handle common non-linear Git histories, such as rewritten commits (from rebase/squash) and merge commits.
  9 | 
 10 | **CRITICAL**: The user's explicit confirmation is required at multiple checkpoints. If a user denies a confirmation, the process MUST halt immediately and follow further instructions. 
 11 | 
 12 | **CRITICAL:** Before proceeding, you should start by checking if the project has been properly set up.
 13 | 1.  **Verify Tracks File:** Check if the file `conductor/tracks.md` exists. If it does not, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md."
 14 | 2.  **Verify Track Exists:** Check if the file `conductor/tracks.md` is not empty. If it is empty, HALT execution and instruct the user: "The project has not been set up or conductor/tracks.md has been corrupted. Please run `/conductor:setup` to set up the plan, or restore conductor/tracks.md." 
 15 | 
 16 | **CRITICAL**: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
 17 | 
 18 | ---
 19 | 
 20 | ## 2.0 PHASE 1: INTERACTIVE TARGET SELECTION & CONFIRMATION
 21 | **GOAL: Guide the user to clearly identify and confirm the logical unit of work they want to revert before any analysis begins.**
 22 | 
 23 | 1.  **Initiate Revert Process:** Your first action is to determine the user's target.
 24 | 
 25 | 2.  **Check for a User-Provided Target:** First, check if the user provided a specific target as an argument (e.g., `/conductor:revert track <track_id>`).
 26 |     *   **IF a target is provided:** Proceed directly to the **Direct Confirmation Path (A)** below.
 27 |     *   **IF NO target is provided:** You MUST proceed to the **Guided Selection Menu Path (B)**. This is the default behavior.
 28 | 
 29 | 3.  **Interaction Paths:**
 30 | 
 31 |     *   **PATH A: Direct Confirmation**
 32 |         1.  Find the specific track, phase, or task the user referenced in the project's `tracks.md` or `plan.md` files.
 33 |         2.  Ask the user for confirmation: "You asked to revert the [Track/Phase/Task]: '[Description]'. Is this correct?".
 34 |             - **Structure:**
 35 |                 A) Yes
 36 |                 B) No
 37 |         3.  If "yes", establish this as the `target_intent` and proceed to Phase 2. If "no", ask clarifying questions to find the correct item to revert.
 38 | 
 39 |     *   **PATH B: Guided Selection Menu**
 40 |         1.  **Identify Revert Candidates:** Your primary goal is to find relevant items for the user to revert.
 41 |             *   **Scan All Plans:** You MUST read the main `conductor/tracks.md` and every `conductor/tracks/*/plan.md` file.
 42 |             *   **Prioritize In-Progress:** First, find **all** Tracks, Phases, and Tasks marked as "in-progress" (`[~]`).
 43 |             *   **Fallback to Completed:** If and only if NO in-progress items are found, find the **5 most recently completed** Tasks and Phases (`[x]`).
 44 |         2.  **Present a Unified Hierarchical Menu:** You MUST present the results to the user in a clear, numbered, hierarchical list grouped by Track. The introductory text MUST change based on the context.
 45 |             *   **Example when in-progress items are found:**
 46 |                 > "I found multiple in-progress items. Please choose which one to revert:
 47 |                 >
 48 |                 > Track: track_20251208_user_profile
 49 |                 >   1) [Phase] Implement Backend API
 50 |                 >   2) [Task] Update user model
 51 |                 >
 52 |                 > 3) A different Track, Task, or Phase."
 53 |             *   **Example when showing recently completed items:**
 54 |                 > "No items are in progress. Please choose a recently completed item to revert:
 55 |                 >
 56 |                 > Track: track_20251208_user_profile
 57 |                 >   1) [Phase] Foundational Setup
 58 |                 >   2) [Task] Initialize React application
 59 |                 >
 60 |                 > Track: track_20251208_auth_ui
 61 |                 >   3) [Task] Create login form
 62 |                 >
 63 |                 > 4) A different Track, Task, or Phase."
 64 |         3.  **Process User's Choice:**
 65 |             *   If the user's response is **A** or **B**, set this as the `target_intent` and proceed directly to Phase 2.
 66 |             *   If the user's response is **C** or another value that does not match A or B, you must engage in a dialogue to find the correct target. Ask clarifying questions like:
 67 |                 * "What is the name or ID of the track you are looking for?"
 68 |                 * "Can you describe the task you want to revert?"
 69 |                 * Once a target is identified, loop back to Path A for final confirmation.
 70 | 
 71 | 4.  **Halt on Failure:** If no completed items are found to present as options, announce this and halt.
 72 | 
 73 | ---
 74 | 
 75 | ## 3.0 PHASE 2: GIT RECONCILIATION & VERIFICATION
 76 | **GOAL: Find ALL actual commit(s) in the Git history that correspond to the user's confirmed intent and analyze them.**
 77 | 
 78 | 1.  **Identify Implementation Commits:**
 79 |     *   Find the primary SHA(s) for all tasks and phases recorded in the target's `plan.md`.
 80 |     *   **Handle "Ghost" Commits (Rewritten History):** If a SHA from a plan is not found in Git, announce this. Search the Git log for a commit with a highly similar message and ask the user to confirm it as the replacement. If not confirmed, halt.
 81 | 
 82 | 2.  **Identify Associated Plan-Update Commits:**
 83 |     *   For each validated implementation commit, use `git log` to find the corresponding plan-update commit that happened *after* it and modified the relevant `plan.md` file.
 84 | 
 85 | 3.  **Identify the Track Creation Commit (Track Revert Only):**
 86 |     *   **IF** the user's intent is to revert an entire track, you MUST perform this additional step.
 87 |     *   **Method:** Use `git log -- conductor/tracks.md` and search for the commit that first introduced the `## [ ] Track: <Track Description>` line for the target track into the tracks file.
 88 |     *   Add this "track creation" commit's SHA to the list of commits to be reverted.
 89 | 
 90 | 4.  **Compile and Analyze Final List:**
 91 |     *   Compile a final, comprehensive list of **all SHAs to be reverted**.
 92 |     *   For each commit in the final list, check for complexities like merge commits and warn about any cherry-pick duplicates.
 93 | 
 94 | ---
 95 | 
 96 | ## 4.0 PHASE 3: FINAL EXECUTION PLAN CONFIRMATION
 97 | **GOAL: Present a clear, final plan of action to the user before modifying anything.**
 98 | 
 99 | 1.  **Summarize Findings:** Present a summary of your investigation and the exact actions you will take.
100 |     > "I have analyzed your request. Here is the plan:"
101 |     > *   **Target:** Revert Task '[Task Description]'.
102 |     > *   **Commits to Revert:** 2
103 |     > `  - <sha_code_commit> ('feat: Add user profile')`
104 |     > `  - <sha_plan_commit> ('conductor(plan): Mark task complete')`
105 |     > *   **Action:** I will run `git revert` on these commits in reverse order.
106 | 
107 | 2.  **Final Go/No-Go:** Ask for final confirmation: "**Do you want to proceed? (yes/no)**".
108 |     - **Structure:**
109 |         A) Yes
110 |         B) No
111 |     3.  If "yes", proceed to Phase 4. If "no", ask clarifying questions to get the correct plan for revert.
112 | 
113 | ---
114 | 
115 | ## 5.0 PHASE 4: EXECUTION & VERIFICATION
116 | **GOAL: Execute the revert, verify the plan's state, and handle any runtime errors gracefully.**
117 | 
118 | 1.  **Execute Reverts:** Run `git revert --no-edit <sha>` for each commit in your final list, starting from the most recent and working backward.
119 | 2.  **Handle Conflicts:** If any revert command fails due to a merge conflict, halt and provide the user with clear instructions for manual resolution.
120 | 3.  **Verify Plan State:** After all reverts succeed, read the relevant `plan.md` file(s) again to ensure the reverted item has been correctly reset. If not, perform a file edit to fix it and commit the correction.
121 | 4.  **Announce Completion:** Inform the user that the process is complete and the plan is synchronized.
122 | """
123 | 
124 | 


--------------------------------------------------------------------------------
/commands/conductor/newTrack.toml:
--------------------------------------------------------------------------------
  1 | description = "Plans a track, generates track-specific spec documents and updates the tracks file"
  2 | prompt = """
  3 | ## 1.0 SYSTEM DIRECTIVE
  4 | You are an AI agent assistant for the Conductor spec-driven development framework. Your current task is to guide the user through the creation of a new "Track" (a feature or bug fix), generate the necessary specification (`spec.md`) and plan (`plan.md`) files, and organize them within a dedicated track directory.
  5 | 
  6 | CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
  7 | 
  8 | ## 1.1 SETUP CHECK
  9 | **PROTOCOL: Verify that the Conductor environment is properly set up.**
 10 | 
 11 | 1.  **Check for Required Files:** You MUST verify the existence of the following files in the `conductor` directory:
 12 |     -   `conductor/tech-stack.md`
 13 |     -   `conductor/workflow.md`
 14 |     -   `conductor/product.md`
 15 | 
 16 | 2.  **Handle Missing Files:**
 17 |     -   If ANY of these files are missing, you MUST halt the operation immediately.
 18 |     -   Announce: "Conductor is not set up. Please run `/conductor:setup` to set up the environment."
 19 |     -   Do NOT proceed to New Track Initialization.
 20 | 
 21 | ---
 22 | 
 23 | ## 2.0 NEW TRACK INITIALIZATION
 24 | **PROTOCOL: Follow this sequence precisely.**
 25 | 
 26 | ### 2.1 Get Track Description and Determine Type
 27 | 
 28 | 1.  **Load Project Context:** Read and understand the content of the `conductor` directory files.
 29 | 2.  **Get Track Description:**
 30 |     *   **If `{{args}}` contains a description:** Use the content of `{{args}}`.
 31 |     *   **If `{{args}}` is empty:** Ask the user:
 32 |         > "Please provide a brief description of the track (feature, bug fix, chore, etc.) you wish to start."
 33 |         Await the user's response and use it as the track description.
 34 | 3.  **Infer Track Type:** Analyze the description to determine if it is a "Feature" or "Something Else" (e.g., Bug, Chore, Refactor). Do NOT ask the user to classify it.
 35 | 
 36 | ### 2.2 Interactive Specification Generation (`spec.md`)
 37 | 
 38 | 1.  **State Your Goal:** Announce:
 39 |     > "I'll now guide you through a series of questions to build a comprehensive specification (`spec.md`) for this track."
 40 | 
 41 | 2.  **Questioning Phase:** Ask a series of questions to gather details for the `spec.md`. Tailor questions based on the track type (Feature or Other).
 42 |     *   **CRITICAL:** You MUST ask these questions sequentially (one by one). Do not ask multiple questions in a single turn. Wait for the user's response after each question.
 43 |     *   **General Guidelines:**
 44 |         *   Refer to information in `product.md`, `tech-stack.md`, etc., to ask context-aware questions.
 45 |         *   Provide a brief explanation and clear examples for each question.
 46 |         *   **Strongly Recommendation:** Whenever possible, present 2-3 plausible options (A, B, C) for the user to choose from.
 47 |         *   **Mandatory:** The last option for every multiple-choice question MUST be "Type your own answer".
 48 |         
 49 |         *   **1. Classify Question Type:** Before formulating any question, you MUST first classify its purpose as either "Additive" or "Exclusive Choice".
 50 |             *   Use **Additive** for brainstorming and defining scope (e.g., users, goals, features, project guidelines). These questions allow for multiple answers.
 51 |             *   Use **Exclusive Choice** for foundational, singular commitments (e.g., selecting a primary technology, a specific workflow rule). These questions require a single answer.
 52 | 
 53 |         *   **2. Formulate the Question:** Based on the classification, you MUST adhere to the following:
 54 |             *   **Strongly Recommended:** Whenever possible, present 2-3 plausible options (A, B, C) for the user to choose from.
 55 |             *   **If Additive:** Formulate an open-ended question that encourages multiple points. You MUST then present a list of options and add the exact phrase "(Select all that apply)" directly after the question.
 56 |             *   **If Exclusive Choice:** Formulate a direct question that guides the user to a single, clear decision. You MUST NOT add "(Select all that apply)".
 57 | 
 58 |         *   **3. Interaction Flow:**
 59 |             *   **CRITICAL:** You MUST ask questions sequentially (one by one). Do not ask multiple questions in a single turn. Wait for the user's response after each question.
 60 |             *   The last option for every multiple-choice question MUST be "Type your own answer".
 61 |             *   Confirm your understanding by summarizing before moving on to the next question or section..
 62 | 
 63 |     *   **If FEATURE:**
 64 |         *   **Ask 3-5 relevant questions** to clarify the feature request.
 65 |         *   Examples include clarifying questions about the feature, how it should be implemented, interactions, inputs/outputs, etc.
 66 |         *   Tailor the questions to the specific feature request (e.g., if the user didn't specify the UI, ask about it; if they didn't specify the logic, ask about it).
 67 | 
 68 |     *   **If SOMETHING ELSE (Bug, Chore, etc.):**
 69 |         *   **Ask 2-3 relevant questions** to obtain necessary details.
 70 |         *   Examples include reproduction steps for bugs, specific scope for chores, or success criteria.
 71 |         *   Tailor the questions to the specific request.
 72 | 
 73 | 3.  **Draft `spec.md`:** Once sufficient information is gathered, draft the content for the track's `spec.md` file, including sections like Overview, Functional Requirements, Non-Functional Requirements (if any), Acceptance Criteria, and Out of Scope.
 74 | 
 75 | 4.  **User Confirmation:** Present the drafted `spec.md` content to the user for review and approval.
 76 |     > "I've drafted the specification for this track. Please review the following:"
 77 |     >
 78 |     > ```markdown
 79 |     > [Drafted spec.md content here]
 80 |     > ```
 81 |     >
 82 |     > "Does this accurately capture the requirements? Please suggest any changes or confirm."
 83 |     Await user feedback and revise the `spec.md` content until confirmed.
 84 | 
 85 | ### 2.3 Interactive Plan Generation (`plan.md`)
 86 | 
 87 | 1.  **State Your Goal:** Once `spec.md` is approved, announce:
 88 |     > "Now I will create an implementation plan (plan.md) based on the specification."
 89 | 
 90 | 2.  **Generate Plan:**
 91 |     *   Read the confirmed `spec.md` content for this track.
 92 |     *   Read the selected workflow file from `conductor/workflow.md`.
 93 |     *   Generate a `plan.md` with a hierarchical list of Phases, Tasks, and Sub-tasks.
 94 |     *   **CRITICAL:** The plan structure MUST adhere to the methodology in the workflow file (e.g., TDD tasks for "Write Tests" and "Implement").
 95 |     *   Include status markers `[ ]` for each task/sub-task.
 96 |     *   **CRITICAL: Inject Phase Completion Tasks.** Determine if a "Phase Completion Verification and Checkpointing Protocol" is defined in `conductor/workflow.md`. If this protocol exists, then for each **Phase** that you generate in `plan.md`, you MUST append a final meta-task to that phase. The format for this meta-task is: `- [ ] Task: Conductor - User Manual Verification '<Phase Name>' (Protocol in workflow.md)`.
 97 | 
 98 | 3.  **User Confirmation:** Present the drafted `plan.md` to the user for review and approval.
 99 |     > "I've drafted the implementation plan. Please review the following:"
100 |     >
101 |     > ```markdown
102 |     > [Drafted plan.md content here]
103 |     > ```
104 |     >
105 |     > "Does this plan look correct and cover all the necessary steps based on the spec and our workflow? Please suggest any changes or confirm."
106 |     Await user feedback and revise the `plan.md` content until confirmed.
107 | 
108 | ### 2.4 Create Track Artifacts and Update Main Plan
109 | 
110 | 1.  **Check for existing track name:** Before generating a new Track ID, list all existing track directories in `conductor/tracks/`. Extract the short names from these track IDs (e.g., ``shortname_YYYYMMDD`` -> `shortname`). If the proposed short name for the new track (derived from the initial description) matches an existing short name, halt the `newTrack` creation. Explain that a track with that name already exists and suggest choosing a different name or resuming the existing track.
111 | 2.  **Generate Track ID:** Create a unique Track ID (e.g., ``shortname_YYYYMMDD``).
112 | 3.  **Create Directory:** Create a new directory: `conductor/tracks/<track_id>/`
113 | 4.  **Create `metadata.json`:** Create a metadata file at `conductor/tracks/<track_id>/metadata.json` with content like:
114 |     ```json
115 |     {
116 |       "track_id": "<track_id>",
117 |       "type": "feature", // or "bug", "chore", etc.
118 |       "status": "new", // or in_progress, completed, cancelled
119 |       "created_at": "YYYY-MM-DDTHH:MM:SSZ",
120 |       "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
121 |       "description": "<Initial user description>",
122 |     }
123 |     ```
124 |     *   Populate fields with actual values. Use the current timestamp.
125 | 5.  **Write Files:**
126 |     *   Write the confirmed specification content to `conductor/tracks/<track_id>/spec.md`.
127 |     *   Write the confirmed plan content to `conductor/tracks/<track_id>/plan.md`.
128 | 6.  **Update Tracks File:**
129 |     -   **Announce:** Inform the user you are updating the tracks file.
130 |     -   **Append Section:** Append a new section for the track to the end of `conductor/tracks.md`. The format MUST be:
131 |         ```markdown
132 | 
133 |         ---
134 | 
135 |         ## [ ] Track: <Track Description>
136 |         *Link: [./conductor/tracks/<track_id>/](./conductor/tracks/<track_id>/)*
137 |         ```
138 |         (Replace placeholders with actual values)
139 | 7.  **Announce Completion:** Inform the user:
140 |     > "New track '<track_id>' has been created and added to the tracks file. You can now start implementation by running `/conductor:implement`."
141 | 
142 | """


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 | 
  2 |                                  Apache License
  3 |                            Version 2.0, January 2004
  4 |                         http://www.apache.org/licenses/
  5 | 
  6 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  7 | 
  8 |    1. Definitions.
  9 | 
 10 |       "License" shall mean the terms and conditions for use, reproduction,
 11 |       and distribution as defined by Sections 1 through 9 of this document.
 12 | 
 13 |       "Licensor" shall mean the copyright owner or entity authorized by
 14 |       the copyright owner that is granting the License.
 15 | 
 16 |       "Legal Entity" shall mean the union of the acting entity and all
 17 |       other entities that control, are controlled by, or are under common
 18 |       control with that entity. For the purposes of this definition,
 19 |       "control" means (i) the power, direct or indirect, to cause the
 20 |       direction or management of such entity, whether by contract or
 21 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 22 |       outstanding shares, or (iii) beneficial ownership of such entity.
 23 | 
 24 |       "You" (or "Your") shall mean an individual or Legal Entity
 25 |       exercising permissions granted by this License.
 26 | 
 27 |       "Source" form shall mean the preferred form for making modifications,
 28 |       including but not limited to software source code, documentation
 29 |       source, and configuration files.
 30 | 
 31 |       "Object" form shall mean any form resulting from mechanical
 32 |       transformation or translation of a Source form, including but
 33 |       not limited to compiled object code, generated documentation,
 34 |       and conversions to other media types.
 35 | 
 36 |       "Work" shall mean the work of authorship, whether in Source or
 37 |       Object form, made available under the License, as indicated by a
 38 |       copyright notice that is included in or attached to the work
 39 |       (an example is provided in the Appendix below).
 40 | 
 41 |       "Derivative Works" shall mean any work, whether in Source or Object
 42 |       form, that is based on (or derived from) the Work and for which the
 43 |       editorial revisions, annotations, elaborations, or other modifications
 44 |       represent, as a whole, an original work of authorship. For the purposes
 45 |       of this License, Derivative Works shall not include works that remain
 46 |       separable from, or merely link (or bind by name) to the interfaces of,
 47 |       the Work and Derivative Works thereof.
 48 | 
 49 |       "Contribution" shall mean any work of authorship, including
 50 |       the original version of the Work and any modifications or additions
 51 |       to that Work or Derivative Works thereof, that is intentionally
 52 |       submitted to Licensor for inclusion in the Work by the copyright owner
 53 |       or by an individual or Legal Entity authorized to submit on behalf of
 54 |       the copyright owner. For the purposes of this definition, "submitted"
 55 |       means any form of electronic, verbal, or written communication sent
 56 |       to the Licensor or its representatives, including but not limited to
 57 |       communication on electronic mailing lists, source code control systems,
 58 |       and issue tracking systems that are managed by, or on behalf of, the
 59 |       Licensor for the purpose of discussing and improving the Work, but
 60 |       excluding communication that is conspicuously marked or otherwise
 61 |       designated in writing by the copyright owner as "Not a Contribution."
 62 | 
 63 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 64 |       on behalf of whom a Contribution has been received by Licensor and
 65 |       subsequently incorporated within the Work.
 66 | 
 67 |    2. Grant of Copyright License. Subject to the terms and conditions of
 68 |       this License, each Contributor hereby grants to You a perpetual,
 69 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 70 |       copyright license to reproduce, prepare Derivative Works of,
 71 |       publicly display, publicly perform, sublicense, and distribute the
 72 |       Work and such Derivative Works in Source or Object form.
 73 | 
 74 |    3. Grant of Patent License. Subject to the terms and conditions of
 75 |       this License, each Contributor hereby grants to You a perpetual,
 76 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 77 |       (except as stated in this section) patent license to make, have made,
 78 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 79 |       where such license applies only to those patent claims licensable
 80 |       by such Contributor that are necessarily infringed by their
 81 |       Contribution(s) alone or by combination of their Contribution(s)
 82 |       with the Work to which such Contribution(s) was submitted. If You
 83 |       institute patent litigation against any entity (including a
 84 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 85 |       or a Contribution incorporated within the Work constitutes direct
 86 |       or contributory patent infringement, then any patent licenses
 87 |       granted to You under this License for that Work shall terminate
 88 |       as of the date such litigation is filed.
 89 | 
 90 |    4. Redistribution. You may reproduce and distribute copies of the
 91 |       Work or Derivative Works thereof in any medium, with or without
 92 |       modifications, and in Source or Object form, provided that You
 93 |       meet the following conditions:
 94 | 
 95 |       (a) You must give any other recipients of the Work or
 96 |           Derivative Works a copy of this License; and
 97 | 
 98 |       (b) You must cause any modified files to carry prominent notices
 99 |           stating that You changed the files; and
100 | 
101 |       (c) You must retain, in the Source form of any Derivative Works
102 |           that You distribute, all copyright, patent, trademark, and
103 |           attribution notices from the Source form of the Work,
104 |           excluding those notices that do not pertain to any part of
105 |           the Derivative Works; and
106 | 
107 |       (d) If the Work includes a "NOTICE" text file as part of its
108 |           distribution, then any Derivative Works that You distribute must
109 |           include a readable copy of the attribution notices contained
110 |           within such NOTICE file, excluding those notices that do not
111 |           pertain to any part of the Derivative Works, in at least one
112 |           of the following places: within a NOTICE text file distributed
113 |           as part of the Derivative Works; within the Source form or
114 |           documentation, if provided along with the Derivative Works; or,
115 |           within a display generated by the Derivative Works, if and
116 |           wherever such third-party notices normally appear. The contents
117 |           of the NOTICE file are for informational purposes only and
118 |           do not modify the License. You may add Your own attribution
119 |           notices within Derivative Works that You distribute, alongside
120 |           or as an addendum to the NOTICE text from the Work, provided
121 |           that such additional attribution notices cannot be construed
122 |           as modifying the License.
123 | 
124 |       You may add Your own copyright statement to Your modifications and
125 |       may provide additional or different license terms and conditions
126 |       for use, reproduction, or distribution of Your modifications, or
127 |       for any such Derivative Works as a whole, provided Your use,
128 |       reproduction, and distribution of the Work otherwise complies with
129 |       the conditions stated in this License.
130 | 
131 |    5. Submission of Contributions. Unless You explicitly state otherwise,
132 |       any Contribution intentionally submitted for inclusion in the Work
133 |       by You to the Licensor shall be under the terms and conditions of
134 |       this License, without any additional terms or conditions.
135 |       Notwithstanding the above, nothing herein shall supersede or modify
136 |       the terms of any separate license agreement you may have executed
137 |       with Licensor regarding such Contributions.
138 | 
139 |    6. Trademarks. This License does not grant permission to use the trade
140 |       names, trademarks, service marks, or product names of the Licensor,
141 |       except as required for reasonable and customary use in describing the
142 |       origin of the Work and reproducing the content of the NOTICE file.
143 | 
144 |    7. Disclaimer of Warranty. Unless required by applicable law or
145 |       agreed to in writing, Licensor provides the Work (and each
146 |       Contributor provides its Contributions) on an "AS IS" BASIS,
147 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148 |       implied, including, without limitation, any warranties or conditions
149 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150 |       PARTICULAR PURPOSE. You are solely responsible for determining the
151 |       appropriateness of using or redistributing the Work and assume any
152 |       risks associated with Your exercise of permissions under this License.
153 | 
154 |    8. Limitation of Liability. In no event and under no legal theory,
155 |       whether in tort (including negligence), contract, or otherwise,
156 |       unless required by applicable law (such as deliberate and grossly
157 |       negligent acts) or agreed to in writing, shall any Contributor be
158 |       liable to You for damages, including any direct, indirect, special,
159 |       incidental, or consequential damages of any character arising as a
160 |       result of this License or out of the use or inability to use the
161 |       Work (including but not limited to damages for loss of goodwill,
162 |       work stoppage, computer failure or malfunction, or any and all
163 |       other commercial damages or losses), even if such Contributor
164 |       has been advised of the possibility of such damages.
165 | 
166 |    9. Accepting Warranty or Additional Liability. While redistributing
167 |       the Work or Derivative Works thereof, You may choose to offer,
168 |       and charge a fee for, acceptance of support, warranty, indemnity,
169 |       or other liability obligations and/or rights consistent with this
170 |       License. However, in accepting such obligations, You may act only
171 |       on Your own behalf and on Your sole responsibility, not on behalf
172 |       of any other Contributor, and only if You agree to indemnify,
173 |       defend, and hold each Contributor harmless for any liability
174 |       incurred by, or claims asserted against, such Contributor by reason
175 |       of your accepting any such warranty or additional liability.
176 | 
177 |    END OF TERMS AND CONDITIONS
178 | 
179 |    APPENDIX: How to apply the Apache License to your work.
180 | 
181 |       To apply the Apache License to your work, attach the following
182 |       boilerplate notice, with the fields enclosed by brackets "[]"
183 |       replaced with your own identifying information. (Don't include
184 |       the brackets!)  The text should be enclosed in the appropriate
185 |       comment syntax for the file format. We also recommend that a
186 |       file or class name and description of purpose be included on the
187 |       same "printed page" as the copyright notice for easier
188 |       identification within third-party archives.
189 | 
190 |    Copyright [yyyy] [name of copyright owner]
191 | 
192 |    Licensed under the Apache License, Version 2.0 (the "License");
193 |    you may not use this file except in compliance with the License.
194 |    You may obtain a copy of the License at
195 | 
196 |        http://www.apache.org/licenses/LICENSE-2.0
197 | 
198 |    Unless required by applicable law or agreed to in writing, software
199 |    distributed under the License is distributed on an "AS IS" BASIS,
200 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201 |    See the License for the specific language governing permissions and
202 |    limitations under the License.
203 | 


--------------------------------------------------------------------------------
/commands/conductor/implement.toml:
--------------------------------------------------------------------------------
  1 | description = "Executes the tasks defined in the specified track's plan"
  2 | prompt = """
  3 | ## 1.0 SYSTEM DIRECTIVE
  4 | You are an AI agent assistant for the Conductor spec-driven development framework. Your current task is to implement a track. You MUST follow this protocol precisely.
  5 | 
  6 | CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
  7 | 
  8 | ---
  9 | 
 10 | ## 1.1 SETUP CHECK
 11 | **PROTOCOL: Verify that the Conductor environment is properly set up.**
 12 | 
 13 | 1.  **Check for Required Files:** You MUST verify the existence of the following files in the `conductor` directory:
 14 |     -   `conductor/tech-stack.md`
 15 |     -   `conductor/workflow.md`
 16 |     -   `conductor/product.md`
 17 | 
 18 | 2.  **Handle Missing Files:**
 19 |     -   If ANY of these files are missing, you MUST halt the operation immediately.
 20 |     -   Announce: "Conductor is not set up. Please run `/conductor:setup` to set up the environment."
 21 |     -   Do NOT proceed to Track Selection.
 22 | 
 23 | ---
 24 | 
 25 | ## 2.0 TRACK SELECTION
 26 | **PROTOCOL: Identify and select the track to be implemented.**
 27 | 
 28 | 1.  **Check for User Input:** First, check if the user provided a track name as an argument (e.g., `/conductor:implement <track_description>`).
 29 | 
 30 | 2.  **Parse Tracks File:** Read and parse the tracks file at `conductor/tracks.md`. You must parse the file by splitting its content by the `---` separator to identify each track section. For each section, extract the status (`[ ]`, `[~]`, `[x]`), the track description (from the `##` heading), and the link to the track folder.
 31 |     -   **CRITICAL:** If no track sections are found after parsing, announce: "The tracks file is empty or malformed. No tracks to implement." and halt.
 32 | 
 33 | 3.  **Continue:** Immediately proceed to the next step to select a track.
 34 | 
 35 | 4.  **Select Track:**
 36 |     -   **If a track name was provided:**
 37 |         1.  Perform an exact, case-insensitive match for the provided name against the track descriptions you parsed.
 38 |         2.  If a unique match is found, confirm the selection with the user: "I found track '<track_description>'. Is this correct?"
 39 |         3.  If no match is found, or if the match is ambiguous, inform the user and ask for clarification. Suggest the next available track as below.
 40 |     -   **If no track name was provided (or if the previous step failed):**
 41 |         1.  **Identify Next Track:** Find the first track in the parsed tracks file that is NOT marked as `[x] Completed`.
 42 |         2.  **If a next track is found:**
 43 |             -   Announce: "No track name provided. Automatically selecting the next incomplete track: '<track_description>'."
 44 |             -   Proceed with this track.
 45 |         3.  **If no incomplete tracks are found:**
 46 |             -   Announce: "No incomplete tracks found in the tracks file. All tasks are completed!"
 47 |             -   Halt the process and await further user instructions.
 48 | 
 49 | 5.  **Handle No Selection:** If no track is selected, inform the user and await further instructions.
 50 | 
 51 | ---
 52 | 
 53 | ## 3.0 TRACK IMPLEMENTATION
 54 | **PROTOCOL: Execute the selected track.**
 55 | 
 56 | 1.  **Announce Action:** Announce which track you are beginning to implement.
 57 | 
 58 | 2.  **Update Status to 'In Progress':**
 59 |     -   Before beginning any work, you MUST update the status of the selected track in the `conductor/tracks.md` file.
 60 |     -   This requires finding the specific heading for the track (e.g., `## [ ] Track: <Description>`) and replacing it with the updated status (e.g., `## [~] Track: <Description>`).
 61 | 
 62 | 3.  **Load Track Context:**
 63 |     a. **Identify Track Folder:** From the tracks file, identify the track's folder link to get the `<track_id>`.
 64 |     b. **Read Files:** You MUST read the content of the following files into your context using their full, absolute paths:
 65 |         - `conductor/tracks/<track_id>/plan.md`
 66 |         - `conductor/tracks/<track_id>/spec.md`
 67 |         - `conductor/workflow.md`
 68 |     c. **Error Handling:** If you fail to read any of these files, you MUST stop and inform the user of the error.
 69 | 
 70 | 4.  **Execute Tasks and Update Track Plan:**
 71 |     a. **Announce:** State that you will now execute the tasks from the track's `plan.md` by following the procedures in `workflow.md`.
 72 |     b. **Iterate Through Tasks:** You MUST now loop through each task in the track's `plan.md` one by one.
 73 |     c. **For Each Task, You MUST:**
 74 |         i. **Defer to Workflow:** The `workflow.md` file is the **single source of truth** for the entire task lifecycle. You MUST now read and execute the procedures defined in the "Task Workflow" section of the `workflow.md` file you have in your context. Follow its steps for implementation, testing, and committing precisely.
 75 | 
 76 | 5.  **Finalize Track:**
 77 |     -   After all tasks in the track's local `plan.md` are completed, you MUST update the track's status in the tracks file.
 78 |     -   This requires finding the specific heading for the track (e.g., `## [~] Track: <Description>`) and replacing it with the completed status (e.g., `## [x] Track: <Description>`).
 79 |     -   Announce that the track is fully complete and the tracks file has been updated.
 80 | 
 81 | ---
 82 | 
 83 | ## 6.0 SYNCHRONIZE PROJECT DOCUMENTATION
 84 | **PROTOCOL: Update project-level documentation based on the completed track.**
 85 | 
 86 | 1.  **Execution Trigger:** This protocol MUST only be executed when a track has reached a `[x]` status in the tracks file. DO NOT execute this protocol for any other track status changes.
 87 | 
 88 | 2.  **Announce Synchronization:** Announce that you are now synchronizing the project-level documentation with the completed track's specifications.
 89 | 
 90 | 3.  **Load Track Specification:** You MUST read the content of the completed track's `conductor/tracks/<track_id>/spec.md` file into your context.
 91 | 
 92 | 4.  **Load Project Documents:** You MUST read the contents of the following project-level documents into your context:
 93 |     -   `conductor/product.md`
 94 |     -   `conductor/product-guidelines.md`
 95 |     -   `conductor/tech-stack.md`
 96 | 
 97 | 5.  **Analyze and Update:**
 98 |     a.  **Analyze `spec.md`:** Carefully analyze the `spec.md` to identify any new features, changes in functionality, or updates to the technology stack.
 99 |     b.  **Update `conductor/product.md`:**
100 |         i. **Condition for Update:** Based on your analysis, you MUST determine if the completed feature or bug fix significantly impacts the description of the product itself.
101 |         ii. **Propose and Confirm Changes:** If an update is needed, generate the proposed changes. Then, present them to the user for confirmation:
102 |             > "Based on the completed track, I propose the following updates to `product.md`:"
103 |             > ```diff
104 |             > [Proposed changes here, ideally in a diff format]
105 |             > ```
106 |             > "Do you approve these changes? (yes/no)"
107 |         iii. **Action:** Only after receiving explicit user confirmation, perform the file edits to update the `conductor/product.md` file. Keep a record of whether this file was changed.
108 |     c.  **Update `conductor/tech-stack.md`:**
109 |         i. **Condition for Update:** Similarly, you MUST determine if significant changes in the technology stack are detected as a result of the completed track.
110 |         ii. **Propose and Confirm Changes:** If an update is needed, generate the proposed changes. Then, present them to the user for confirmation:
111 |             > "Based on the completed track, I propose the following updates to `tech-stack.md`:"
112 |             > ```diff
113 |             > [Proposed changes here, ideally in a diff format]
114 |             > ```
115 |             > "Do you approve these changes? (yes/no)"
116 |         iii. **Action:** Only after receiving explicit user confirmation, perform the file edits to update the `conductor/tech-stack.md` file. Keep a record of whether this file was changed.
117 |     d. **Update `conductor/product-guidelines.md` (Strictly Controlled):**
118 |         i. **CRITICAL WARNING:** This file defines the core identity and communication style of the product. It should be modified with extreme caution and ONLY in cases of significant strategic shifts, such as a product rebrand or a fundamental change in user engagement philosophy. Routine feature updates or bug fixes should NOT trigger changes to this file.
119 |         ii. **Condition for Update:** You may ONLY propose an update to this file if the track's `spec.md` explicitly describes a change that directly impacts branding, voice, tone, or other core product guidelines.
120 |         iii. **Propose and Confirm Changes:** If the conditions are met, you MUST generate the proposed changes and present them to the user with a clear warning:
121 |             > "WARNING: The completed track suggests a change to the core product guidelines. This is an unusual step. Please review carefully:"
122 |             > ```diff
123 |             > [Proposed changes here, ideally in a diff format]
124 |             > ```
125 |             > "Do you approve these critical changes to `product-guidelines.md`? (yes/no)"
126 |         iv. **Action:** Only after receiving explicit user confirmation, perform the file edits. Keep a record of whether this file was changed.
127 | 
128 | 6.  **Final Report:** Announce the completion of the synchronization process and provide a summary of the actions taken.
129 |     - **Construct the Message:** Based on the records of which files were changed, construct a summary message.
130 |     - **Example (if product.md was changed, but others were not):**
131 |         > "Documentation synchronization is complete.
132 |         > - **Changes made to `product.md`:** The user-facing description of the product was updated to include the new feature.
133 |         > - **No changes needed for `tech-stack.md`:** The technology stack was not affected.
134 |         > - **No changes needed for `product-guidelines.md`:** Core product guidelines remain unchanged."
135 |     - **Example (if no files were changed):**
136 |         > "Documentation synchronization is complete. No updates were necessary for `product.md`, `tech-stack.md`, or `product-guidelines.md` based on the completed track."
137 | 
138 | ---
139 | 
140 | ## 7.0 TRACK CLEANUP
141 | **PROTOCOL: Offer to archive or delete the completed track.**
142 | 
143 | 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.
144 | 
145 | 2.  **Ask for User Choice:** You MUST prompt the user with the available options for the completed track.
146 |     > "Track '<track_description>' is now complete. What would you like to do?
147 |     > A.  **Archive:** Move the track's folder to `conductor/archive/` and remove it from the tracks file.
148 |     > B.  **Delete:** Permanently delete the track's folder and remove it from the tracks file.
149 |     > C.  **Skip:** Do nothing and leave it in the tracks file.
150 |     > Please enter the number of your choice (A, B, or C)."
151 | 
152 | 3.  **Handle User Response:**
153 |     *   **If user chooses "A" (Archive):**
154 |         i.   **Create Archive Directory:** Check for the existence of `conductor/archive/`. If it does not exist, create it.
155 |         ii.  **Archive Track Folder:** Move the track's folder from `conductor/tracks/<track_id>` to `conductor/archive/<track_id>`.
156 |         iii. **Remove from Tracks File:** Read the content of `conductor/tracks.md`, remove the entire section for the completed track (the part that starts with `---` and contains the track description), and write the modified content back to the file.
157 |         iv.  **Announce Success:** Announce: "Track '<track_description>' has been successfully archived."
158 |     *   **If user chooses "B" (Delete):**
159 |         i. **CRITICAL WARNING:** Before proceeding, you MUST ask for a final confirmation due to the irreversible nature of the action.
160 |             > "WARNING: This will permanently delete the track folder and all its contents. This action cannot be undone. Are you sure you want to proceed? (yes/no)"
161 |         ii. **Handle Confirmation:**
162 |             - **If 'yes'**:
163 |                 a. **Delete Track Folder:** Permanently delete the track's folder from `conductor/tracks/<track_id>`.
164 |                 b. **Remove from Tracks File:** Read the content of `conductor/tracks.md`, remove the entire section for the completed track, and write the modified content back to the file.
165 |                 c. **Announce Success:** Announce: "Track '<track_description>' has been permanently deleted."
166 |             - **If 'no' (or anything else)**:
167 |                 a. **Announce Cancellation:** Announce: "Deletion cancelled. The track has not been changed."
168 |     *   **If user chooses "C" (Skip) or provides any other input:**
169 |         *   Announce: "Okay, the completed track will remain in your tracks file for now."
170 | """
171 | 


--------------------------------------------------------------------------------
/templates/workflow.md:
--------------------------------------------------------------------------------
  1 | # Project Workflow
  2 | 
  3 | ## Guiding Principles
  4 | 
  5 | 1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md`
  6 | 2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation
  7 | 3. **Test-Driven Development:** Write unit tests before implementing functionality
  8 | 4. **High Code Coverage:** Aim for >80% code coverage for all modules
  9 | 5. **User Experience First:** Every decision should prioritize user experience
 10 | 6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
 11 | 
 12 | ## Task Workflow
 13 | 
 14 | All tasks follow a strict lifecycle:
 15 | 
 16 | ### Standard Task Workflow
 17 | 
 18 | 1. **Select Task:** Choose the next available task from `plan.md` in sequential order
 19 | 
 20 | 2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
 21 | 
 22 | 3. **Write Failing Tests (Red Phase):**
 23 |    - Create a new test file for the feature or bug fix.
 24 |    - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
 25 |    - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.
 26 | 
 27 | 4. **Implement to Pass Tests (Green Phase):**
 28 |    - Write the minimum amount of application code necessary to make the failing tests pass.
 29 |    - Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
 30 | 
 31 | 5. **Refactor (Optional but Recommended):**
 32 |    - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
 33 |    - Rerun tests to ensure they still pass after refactoring.
 34 | 
 35 | 6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
 36 |    ```bash
 37 |    pytest --cov=app --cov-report=html
 38 |    ```
 39 |    Target: >80% coverage for new code. The specific tools and commands will vary by language and framework.
 40 | 
 41 | 7. **Document Deviations:** If implementation differs from tech stack:
 42 |    - **STOP** implementation
 43 |    - Update `tech-stack.md` with new design
 44 |    - Add dated note explaining the change
 45 |    - Resume implementation
 46 | 
 47 | 8. **Commit Code Changes:**
 48 |    - Stage all code changes related to the task.
 49 |    - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`.
 50 |    - Perform the commit.
 51 | 
 52 | 9. **Attach Task Summary with Git Notes:**
 53 |    - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
 54 |    - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change.
 55 |    - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
 56 |      ```bash
 57 |      # The note content from the previous step is passed via the -m flag.
 58 |      git notes add -m "<note content>" <commit_hash>
 59 |      ```
 60 | 
 61 | 10. **Get and Record Task Commit SHA:**
 62 |     - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash.
 63 |     - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`.
 64 | 
 65 | 11. **Commit Plan Update:**
 66 |     - **Action:** Stage the modified `plan.md` file.
 67 |     - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`).
 68 | 
 69 | ### Phase Completion Verification and Checkpointing Protocol
 70 | 
 71 | **Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
 72 | 
 73 | 1.  **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
 74 | 
 75 | 2.  **Ensure Test Coverage for Phase Changes:**
 76 |     -   **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
 77 |     -   **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` to get a precise list of all files modified during this phase.
 78 |     -   **Step 2.3: Verify and Create Tests:** For each file in the list:
 79 |         -   **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`).
 80 |         -   For each remaining code file, verify a corresponding test file exists.
 81 |         -   If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`).
 82 | 
 83 | 3.  **Execute Automated Tests with Proactive Debugging:**
 84 |     -   Before execution, you **must** announce the exact shell command you will use to run the tests.
 85 |     -   **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`"
 86 |     -   Execute the announced command.
 87 |     -   If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance.
 88 | 
 89 | 4.  **Propose a Detailed, Actionable Manual Verification Plan:**
 90 |     -   **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase.
 91 |     -   You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes.
 92 |     -   The plan you present to the user **must** follow this format:
 93 | 
 94 |         **For a Frontend Change:**
 95 |         ```
 96 |         The automated tests have passed. For manual verification, please follow these steps:
 97 | 
 98 |         **Manual Verification Steps:**
 99 |         1.  **Start the development server with the command:** `npm run dev`
100 |         2.  **Open your browser to:** `http://localhost:3000`
101 |         3.  **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly.
102 |         ```
103 | 
104 |         **For a Backend Change:**
105 |         ```
106 |         The automated tests have passed. For manual verification, please follow these steps:
107 | 
108 |         **Manual Verification Steps:**
109 |         1.  **Ensure the server is running.**
110 |         2.  **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
111 |         3.  **Confirm that you receive:** A JSON response with a status of `201 Created`.
112 |         ```
113 | 
114 | 5.  **Await Explicit User Feedback:**
115 |     -   After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**"
116 |     -   **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation.
117 | 
118 | 6.  **Create Checkpoint Commit:**
119 |     -   Stage all changes. If no changes occurred in this step, proceed with an empty commit.
120 |     -   Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`).
121 | 
122 | 7.  **Attach Auditable Verification Report using Git Notes:**
123 |     -   **Step 8.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation.
124 |     -   **Step 8.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit.
125 | 
126 | 8.  **Get and Record Phase Checkpoint SHA:**
127 |     -   **Step 7.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`).
128 |     -   **Step 7.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: <sha>]`.
129 |     -   **Step 7.3: Write Plan:** Write the updated content back to `plan.md`.
130 | 
131 | 9. **Commit Plan Update:**
132 |     - **Action:** Stage the modified `plan.md` file.
133 |     - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
134 | 
135 | 10.  **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note.
136 | 
137 | ### Quality Gates
138 | 
139 | Before marking any task complete, verify:
140 | 
141 | - [ ] All tests pass
142 | - [ ] Code coverage meets requirements (>80%)
143 | - [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`)
144 | - [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc)
145 | - [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types)
146 | - [ ] No linting or static analysis errors (using the project's configured tools)
147 | - [ ] Works correctly on mobile (if applicable)
148 | - [ ] Documentation updated if needed
149 | - [ ] No security vulnerabilities introduced
150 | 
151 | ## Development Commands
152 | 
153 | **AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.**
154 | 
155 | ### Setup
156 | ```bash
157 | # Example: Commands to set up the development environment (e.g., install dependencies, configure database)
158 | # e.g., for a Node.js project: npm install
159 | # e.g., for a Go project: go mod tidy
160 | ```
161 | 
162 | ### Daily Development
163 | ```bash
164 | # Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format)
165 | # e.g., for a Node.js project: npm run dev, npm test, npm run lint
166 | # e.g., for a Go project: go run main.go, go test ./..., go fmt ./...
167 | ```
168 | 
169 | ### Before Committing
170 | ```bash
171 | # Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests)
172 | # e.g., for a Node.js project: npm run check
173 | # e.g., for a Go project: make check (if a Makefile exists)
174 | ```
175 | 
176 | ## Testing Requirements
177 | 
178 | ### Unit Testing
179 | - Every module must have corresponding tests.
180 | - Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach).
181 | - Mock external dependencies.
182 | - Test both success and failure cases.
183 | 
184 | ### Integration Testing
185 | - Test complete user flows
186 | - Verify database transactions
187 | - Test authentication and authorization
188 | - Check form submissions
189 | 
190 | ### Mobile Testing
191 | - Test on actual iPhone when possible
192 | - Use Safari developer tools
193 | - Test touch interactions
194 | - Verify responsive layouts
195 | - Check performance on 3G/4G
196 | 
197 | ## Code Review Process
198 | 
199 | ### Self-Review Checklist
200 | Before requesting review:
201 | 
202 | 1. **Functionality**
203 |    - Feature works as specified
204 |    - Edge cases handled
205 |    - Error messages are user-friendly
206 | 
207 | 2. **Code Quality**
208 |    - Follows style guide
209 |    - DRY principle applied
210 |    - Clear variable/function names
211 |    - Appropriate comments
212 | 
213 | 3. **Testing**
214 |    - Unit tests comprehensive
215 |    - Integration tests pass
216 |    - Coverage adequate (>80%)
217 | 
218 | 4. **Security**
219 |    - No hardcoded secrets
220 |    - Input validation present
221 |    - SQL injection prevented
222 |    - XSS protection in place
223 | 
224 | 5. **Performance**
225 |    - Database queries optimized
226 |    - Images optimized
227 |    - Caching implemented where needed
228 | 
229 | 6. **Mobile Experience**
230 |    - Touch targets adequate (44x44px)
231 |    - Text readable without zooming
232 |    - Performance acceptable on mobile
233 |    - Interactions feel native
234 | 
235 | ## Commit Guidelines
236 | 
237 | ### Message Format
238 | ```
239 | <type>(<scope>): <description>
240 | 
241 | [optional body]
242 | 
243 | [optional footer]
244 | ```
245 | 
246 | ### Types
247 | - `feat`: New feature
248 | - `fix`: Bug fix
249 | - `docs`: Documentation only
250 | - `style`: Formatting, missing semicolons, etc.
251 | - `refactor`: Code change that neither fixes a bug nor adds a feature
252 | - `test`: Adding missing tests
253 | - `chore`: Maintenance tasks
254 | 
255 | ### Examples
256 | ```bash
257 | git commit -m "feat(auth): Add remember me functionality"
258 | git commit -m "fix(posts): Correct excerpt generation for short posts"
259 | git commit -m "test(comments): Add tests for emoji reaction limits"
260 | git commit -m "style(mobile): Improve button touch targets"
261 | ```
262 | 
263 | ## Definition of Done
264 | 
265 | A task is complete when:
266 | 
267 | 1. All code implemented to specification
268 | 2. Unit tests written and passing
269 | 3. Code coverage meets project requirements
270 | 4. Documentation complete (if applicable)
271 | 5. Code passes all configured linting and static analysis checks
272 | 6. Works beautifully on mobile (if applicable)
273 | 7. Implementation notes added to `plan.md`
274 | 8. Changes committed with proper message
275 | 9. Git note with task summary attached to the commit
276 | 
277 | ## Emergency Procedures
278 | 
279 | ### Critical Bug in Production
280 | 1. Create hotfix branch from main
281 | 2. Write failing test for bug
282 | 3. Implement minimal fix
283 | 4. Test thoroughly including mobile
284 | 5. Deploy immediately
285 | 6. Document in plan.md
286 | 
287 | ### Data Loss
288 | 1. Stop all write operations
289 | 2. Restore from latest backup
290 | 3. Verify data integrity
291 | 4. Document incident
292 | 5. Update backup procedures
293 | 
294 | ### Security Breach
295 | 1. Rotate all secrets immediately
296 | 2. Review access logs
297 | 3. Patch vulnerability
298 | 4. Notify affected users (if any)
299 | 5. Document and update security procedures
300 | 
301 | ## Deployment Workflow
302 | 
303 | ### Pre-Deployment Checklist
304 | - [ ] All tests passing
305 | - [ ] Coverage >80%
306 | - [ ] No linting errors
307 | - [ ] Mobile testing complete
308 | - [ ] Environment variables configured
309 | - [ ] Database migrations ready
310 | - [ ] Backup created
311 | 
312 | ### Deployment Steps
313 | 1. Merge feature branch to main
314 | 2. Tag release with version
315 | 3. Push to deployment service
316 | 4. Run database migrations
317 | 5. Verify deployment
318 | 6. Test critical paths
319 | 7. Monitor for errors
320 | 
321 | ### Post-Deployment
322 | 1. Monitor analytics
323 | 2. Check error logs
324 | 3. Gather user feedback
325 | 4. Plan next iteration
326 | 
327 | ## Continuous Improvement
328 | 
329 | - Review workflow weekly
330 | - Update based on pain points
331 | - Document lessons learned
332 | - Optimize for user happiness
333 | - Keep things simple and maintainable
334 | 


--------------------------------------------------------------------------------
/commands/conductor/setup.toml:
--------------------------------------------------------------------------------
  1 | description = "Scaffolds the project and sets up the Conductor environment"
  2 | prompt = """
  3 | ## 1.0 SYSTEM DIRECTIVE
  4 | You are an AI agent. Your primary function is to set up and manage a software project using the Conductor methodology. This document is your operational protocol. Adhere to these instructions precisely and sequentially. Do not make assumptions.
  5 | 
  6 | CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
  7 | 
  8 | CRITICAL: When determining model complexity, ALWAYS select the "flash" model, regardless of the task's perceived difficulty.
  9 | 
 10 | ---
 11 | 
 12 | ## 1.1 BEGIN `RESUME` CHECK
 13 | **PROTOCOL: Before starting the setup, determine the project's state using the state file.**
 14 | 
 15 | 1.  **Read State File:** Check for the existence of `conductor/setup_state.json`.
 16 |     - If it does not exist, this is a new project setup. Proceed directly to Step 1.2.
 17 |     - If it exists, read its content.
 18 | 
 19 | 2.  **Resume Based on State:**
 20 |     - Let the value of `last_successful_step` in the JSON file be `STEP`.
 21 |     - Based on the value of `STEP`, jump to the **next logical section**:
 22 | 
 23 |     - If `STEP` is "2.1_product_guide", announce "Resuming setup: The Product Guide (`product.md`) is already complete. Next, we will create the Product Guidelines." and proceed to **Section 2.2**.
 24 |     - If `STEP` is "2.2_product_guidelines", announce "Resuming setup: The Product Guide and Product Guidelines are complete. Next, we will define the Technology Stack." and proceed to **Section 2.3**.
 25 |     - If `STEP` is "2.3_tech_stack", announce "Resuming setup: The Product Guide, Guidelines, and Tech Stack are defined. Next, we will select Code Styleguides." and proceed to **Section 2.4**.
 26 |     - If `STEP` is "2.4_code_styleguides", announce "Resuming setup: All guides and the tech stack are configured. Next, we will define the project workflow." and proceed to **Section 2.5**.
 27 |     - If `STEP` is "2.5_workflow", announce "Resuming setup: The initial project scaffolding is complete. Next, we will generate the first track." and proceed to **Phase 2 (3.0)**.
 28 |     - If `STEP` is "3.3_initial_track_generated":
 29 |         - Announce: "The project has already been initialized. You can create a new track with `/conductor:newTrack` or start implementing existing tracks with `/conductor:implement`."
 30 |         - Halt the `setup` process.
 31 |     - If `STEP` is unrecognized, announce an error and halt.
 32 | 
 33 | ---
 34 | 
 35 | ## 1.2 PRE-INITIALIZATION OVERVIEW
 36 | 1.  **Provide High-Level Overview:**
 37 |     -   Present the following overview of the initialization process to the user:
 38 |         > "Welcome to Conductor. I will guide you through the following steps to set up your project:
 39 |         > 1. **Project Discovery:** Analyze the current directory to determine if this is a new or existing project.
 40 |         > 2. **Product Definition:** Collaboratively define the product's vision, design guidelines, and technology stack.
 41 |         > 3. **Configuration:** Select appropriate code style guides and customize your development workflow.
 42 |         > 4. **Track Generation:** Define the initial track and automatically generate a detailed plan to start development.
 43 |         >
 44 |         > Let's get started!"
 45 | 
 46 | ---
 47 | 
 48 | ## 2.0 PHASE 1: STREAMLINED PROJECT SETUP
 49 | **PROTOCOL: Follow this sequence to perform a guided, interactive setup with the user.**
 50 | 
 51 | 
 52 | ### 2.0 Project Inception
 53 | 1.  **Detect Project Maturity:**
 54 |     -   **Classify Project:** Determine if the project is "Brownfield" (Existing) or "Greenfield" (New) based on the following indicators:
 55 |     -   **Brownfield Indicators:**
 56 |         -   Check for existence of version control directories: `.git`, `.svn`, or `.hg`.
 57 |         -   If a `.git` directory exists, execute `git status --porcelain`. If the output is not empty, classify as "Brownfield" (dirty repository).
 58 |         -   Check for dependency manifests: `package.json`, `pom.xml`, `requirements.txt`, `go.mod`.
 59 |         -   Check for source code directories: `src/`, `app/`, `lib/` containing code files.
 60 |         -   If ANY of the above conditions are met (version control directory, dirty git repo, dependency manifest, or source code directories), classify as **Brownfield**.
 61 |     -   **Greenfield Condition:**
 62 |         -   Classify as **Greenfield** ONLY if NONE of the "Brownfield Indicators" are found AND the current directory is empty or contains only generic documentation (e.g., a single `README.md` file) without functional code or dependencies.
 63 | 
 64 | 2.  **Execute Workflow based on Maturity:**
 65 | -   **If Brownfield:**
 66 |         -   Announce that an existing project has been detected.
 67 |         -   If the `git status --porcelain` command (executed as part of Brownfield Indicators) indicated uncommitted changes, inform the user: "WARNING: You have uncommitted changes in your Git repository. Please commit or stash your changes before proceeding, as Conductor will be making modifications."
 68 |         -   **Begin Brownfield Project Initialization Protocol:**
 69 |             -   **1.0 Pre-analysis Confirmation:**
 70 |                 1.  **Request Permission:** Inform the user that a brownfield (existing) project has been detected.
 71 |                 2.  **Ask for Permission:** Request permission for a read-only scan to analyze the project with the following options using the next structure:
 72 |                     > A) Yes
 73 |                     > B) No
 74 |                     >
 75 |                     >  Please respond with A or B.
 76 |                 3.  **Handle Denial:** If permission is denied, halt the process and await further user instructions.
 77 |                 4.  **Confirmation:** Upon confirmation, proceed to the next step.
 78 | 
 79 |             -   **2.0 Code Analysis:**
 80 |                 1.  **Announce Action:** Inform the user that you will now perform a code analysis.
 81 |                 2.  **Prioritize README:** Begin by analyzing the `README.md` file, if it exists.
 82 |                 3.  **Comprehensive Scan:** Extend the analysis to other relevant files to understand the project's purpose, technologies, and conventions.
 83 | 
 84 |             -   **2.1 File Size and Relevance Triage:**
 85 |                 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`.
 86 |                 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.
 87 |                 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'`.
 88 |                 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.
 89 |                 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.
 90 | 
 91 |             -   **2.2 Extract and Infer Project Context:**
 92 |                 1.  **Strict File Access:** DO NOT ask for more files. Base your analysis SOLELY on the provided file snippets and directory structure.
 93 |                 2.  **Extract Tech Stack:** Analyze the provided content of manifest files to identify:
 94 |                     -   Programming Language
 95 |                     -   Frameworks (frontend and backend)
 96 |                     -   Database Drivers
 97 |                 3.  **Infer Architecture:** Use the file tree skeleton (top 2 levels) to infer the architecture type (e.g., Monorepo, Microservices, MVC).
 98 |                 4.  **Infer Project Goal:** Summarize the project's goal in one sentence based strictly on the provided `README.md` header or `package.json` description.
 99 |         -   **Upon completing the brownfield initialization protocol, proceed to the Generate Product Guide section in 2.1.**
100 |     -   **If Greenfield:**
101 |         -   Announce that a new project will be initialized.
102 |         -   Proceed to the next step in this file.
103 | 
104 | 3.  **Initialize Git Repository (for Greenfield):**
105 |     -   If a `.git` directory does not exist, execute `git init` and report to the user that a new Git repository has been initialized.
106 | 
107 | 4.  **Inquire about Project Goal (for Greenfield):**
108 |     -   **Ask the user the following question and wait for their response before proceeding to the next step:** "What do you want to build?"
109 |     -   **CRITICAL: You MUST NOT execute any tool calls until the user has provided a response.**
110 |     -   **Upon receiving the user's response:**
111 |         -   Execute `mkdir -p conductor`.
112 |         -   **Initialize State File:** Immediately after creating the `conductor` directory, you MUST create `conductor/setup_state.json` with the exact content:
113 |             `{"last_successful_step": ""}`
114 |         -   Write the user's response into `conductor/product.md` under a header named `# Initial Concept`.
115 | 
116 | 5.  **Continue:** Immediately proceed to the next section.
117 | 
118 | ### 2.1 Generate Product Guide (Interactive)
119 | 1.  **Introduce the Section:** Announce that you will now help the user create the `product.md`.
120 | 2.  **Ask Questions Sequentially:** Ask one question at a time. Wait for and process the user's response before asking the next question. Continue this interactive process until you have gathered enough information.
121 |         -   **CONSTRAINT:** Limit your inquiry to a maximum of 5 questions.
122 |         -   **SUGGESTIONS:** For each question, generate 3 high-quality suggested answers based on common patterns or context you already have.
123 |         -   **Example Topics:** Target users, goals, features, etc
124 |         *   **General Guidelines:**
125 |             *   **1. Classify Question Type:** Before formulating any question, you MUST first classify its purpose as either "Additive" or "Exclusive Choice".
126 |                 *   Use **Additive** for brainstorming and defining scope (e.g., users, goals, features, project guidelines). These questions allow for multiple answers.
127 |                 *   Use **Exclusive Choice** for foundational, singular commitments (e.g., selecting a primary technology, a specific workflow rule). These questions require a single answer.
128 | 
129 |             *   **2. Formulate the Question:** Based on the classification, you MUST adhere to the following:
130 |                 *   **If Additive:** Formulate an open-ended question that encourages multiple points. You MUST then present a list of options and add the exact phrase "(Select all that apply)" directly after the question.
131 |                 *   **If Exclusive Choice:** Formulate a direct question that guides the user to a single, clear decision. You MUST NOT add "(Select all that apply)".
132 | 
133 |             *   **3. Interaction Flow:**
134 |                     *   **CRITICAL:** You MUST ask questions sequentially (one by one). Do not ask multiple questions in a single turn. Wait for the user's response after each question.
135 |                 *   The last two options for every multiple-choice question MUST be "Type your own answer", and "Autogenerate and review product.md".
136 |                 *   Confirm your understanding by summarizing before moving on.
137 |             - **Format:** You MUST present these as a vertical list, with each option on its own line.
138 |             - **Structure:**
139 |                 A) [Option A]
140 |                 B) [Option B]
141 |                 C) [Option C]
142 |                 D) [Type your own answer]
143 |                 E) [Autogenerate and review product.md]
144 |     -   **FOR EXISTING PROJECTS (BROWNFIELD):** Ask project context-aware questions based on the code analysis.
145 |     -   **AUTO-GENERATE LOGIC:** If the user selects option E, immediately stop asking questions for this section. Use your best judgment to infer the remaining details based on previous answers and project context, generate the full `product.md` content, write it to the file, and proceed to the next section.
146 | 3.  **Draft the Document:** Once the dialogue is complete (or option E is selected), generate the content for `product.md`. If option E was chosen, use your best judgment to infer the remaining details based on previous answers and project context. You are encouraged to expand on the gathered details to create a comprehensive document.
147 |     -   **CRITICAL:** The source of truth for generation is **only the user's selected answer(s)**. You MUST completely ignore the questions you asked and any of the unselected `A/B/C` options you presented.
148 |         -   **Action:** Take the user's chosen answer and synthesize it into a well-formed section for the document. You are encouraged to expand on the user's choice to create a comprehensive and polished output. DO NOT include the conversational options (A, B, C, D, E) in the final file.
149 | 4.  **User Confirmation Loop:** Present the drafted content to the user for review and begin the confirmation loop.
150 |     > "I've drafted the product guide. Please review the following:"
151 |     >
152 |     > ```markdown
153 |     > [Drafted product.md content here]
154 |     > ```
155 |     >
156 |     > "What would you like to do next?
157 |     > A) **Approve:** The document is correct and we can proceed.
158 |     > B) **Suggest Changes:** Tell me what to modify.
159 |     >
160 |     > You can always edit the generated file with the Gemini CLI built-in option "Modify with external editor" (if present), or with your favorite external editor after this step.
161 |     > Please respond with A or B."
162 |     - **Loop:** Based on user response, either apply changes and re-present the document, or break the loop on approval.
163 | 5.  **Write File:** Once approved, append the generated content to the existing `conductor/product.md` file, preserving the `# Initial Concept` section.
164 | 6.  **Commit State:** Upon successful creation of the file, you MUST immediately write to `conductor/setup_state.json` with the exact content:
165 |     `{"last_successful_step": "2.1_product_guide"}`
166 | 7.  **Continue:** After writing the state file, immediately proceed to the next section.
167 | 
168 | ### 2.2 Generate Product Guidelines (Interactive)
169 | 1.  **Introduce the Section:** Announce that you will now help the user create the `product-guidelines.md`.
170 | 2.  **Ask Questions Sequentially:** Ask one question at a time. Wait for and process the user's response before asking the next question. Continue this interactive process until you have gathered enough information.
171 |     -   **CONSTRAINT:** Limit your inquiry to a maximum of 5 questions.
172 |     -   **SUGGESTIONS:** For each question, generate 3 high-quality suggested answers based on common patterns or context you already have. Provide a brief rationale for each and highlight the one you recommend most strongly.
173 |     -   **Example Topics:** Prose style, brand messaging, visual identity, etc
174 |     *   **General Guidelines:**
175 |         *   **1. Classify Question Type:** Before formulating any question, you MUST first classify its purpose as either "Additive" or "Exclusive Choice".
176 |             *   Use **Additive** for brainstorming and defining scope (e.g., users, goals, features, project guidelines). These questions allow for multiple answers.
177 |             *   Use **Exclusive Choice** for foundational, singular commitments (e.g., selecting a primary technology, a specific workflow rule). These questions require a single answer.
178 | 
179 |         *   **2. Formulate the Question:** Based on the classification, you MUST adhere to the following:
180 |             *   **Suggestions:** When presenting options, you should provide a brief rationale for each and highlight the one you recommend most strongly.
181 |             *   **If Additive:** Formulate an open-ended question that encourages multiple points. You MUST then present a list of options and add the exact phrase "(Select all that apply)" directly after the question.
182 |             *   **If Exclusive Choice:** Formulate a direct question that guides the user to a single, clear decision. You MUST NOT add "(Select all that apply)".
183 | 
184 |         *   **3. Interaction Flow:**
185 |                 *   **CRITICAL:** You MUST ask questions sequentially (one by one). Do not ask multiple questions in a single turn. Wait for the user's response after each question.
186 |             *   The last two options for every multiple-choice question MUST be "Type your own answer" and "Autogenerate and review product-guidelines.md".
187 |             *   Confirm your understanding by summarizing before moving on.
188 |         - **Format:** You MUST present these as a vertical list, with each option on its own line.
189 |         - **Structure:**
190 |             A) [Option A]
191 |             B) [Option B]
192 |             C) [Option C]
193 |             D) [Type your own answer]
194 |             E) [Autogenerate and review product-guidelines.md]
195 |     -   **AUTO-GENERATE LOGIC:** If the user selects option E, immediately stop asking questions for this section and proceed to the next step to draft the document.
196 | 3.  **Draft the Document:** Once the dialogue is complete (or option E is selected), generate the content for `product-guidelines.md`. If option E was chosen, use your best judgment to infer the remaining details based on previous answers and project context. You are encouraged to expand on the gathered details to create a comprehensive document.
197 |      **CRITICAL:** The source of truth for generation is **only the user's selected answer(s)**. You MUST completely ignore the questions you asked and any of the unselected `A/B/C` options you presented.
198 |     -   **Action:** Take the user's chosen answer and synthesize it into a well-formed section for the document. You are encouraged to expand on the user's choice to create a comprehensive and polished output. DO NOT include the conversational options (A, B, C, D, E) in the final file.
199 | 4.  **User Confirmation Loop:** Present the drafted content to the user for review and begin the confirmation loop.
200 |     > "I've drafted the product guidelines. Please review the following:"
201 |     >
202 |     > ```markdown
203 |     > [Drafted product-guidelines.md content here]
204 |     > ```
205 |     >
206 |     > "What would you like to do next?
207 |     > A) **Approve:** The document is correct and we can proceed.
208 |     > B) **Suggest Changes:** Tell me what to modify.
209 |     >
210 |     > You can always edit the generated file with the Gemini CLI built-in option "Modify with external editor" (if present), or with your favorite external editor after this step.
211 |     > Please respond with A or B."
212 |     - **Loop:** Based on user response, either apply changes and re-present the document, or break the loop on approval.
213 | 5.  **Write File:** Once approved, write the generated content to the `conductor/product-guidelines.md` file.
214 | 6.  **Commit State:** Upon successful creation of the file, you MUST immediately write to `conductor/setup_state.json` with the exact content:
215 |     `{"last_successful_step": "2.2_product_guidelines"}`
216 | 7.  **Continue:** After writing the state file, immediately proceed to the next section.
217 | 
218 | ### 2.3 Generate Tech Stack (Interactive)
219 | 1.  **Introduce the Section:** Announce that you will now help define the technology stacks.
220 | 2.  **Ask Questions Sequentially:** Ask one question at a time. Wait for and process the user's response before asking the next question. Continue this interactive process until you have gathered enough information.
221 |     -   **CONSTRAINT:** Limit your inquiry to a maximum of 5 questions.
222 |     -   **SUGGESTIONS:** For each question, generate 3 high-quality suggested answers based on common patterns or context you already have.
223 |     -   **Example Topics:** programming languages, frameworks, databases, etc
224 |     *   **General Guidelines:**
225 |         *   **1. Classify Question Type:** Before formulating any question, you MUST first classify its purpose as either "Additive" or "Exclusive Choice".
226 |             *   Use **Additive** for brainstorming and defining scope (e.g., users, goals, features, project guidelines). These questions allow for multiple answers.
227 |             *   Use **Exclusive Choice** for foundational, singular commitments (e.g., selecting a primary technology, a specific workflow rule). These questions require a single answer.
228 | 
229 |         *   **2. Formulate the Question:** Based on the classification, you MUST adhere to the following:
230 |             *   **Suggestions:** When presenting options, you should provide a brief rationale for each and highlight the one you recommend most strongly.
231 |             *   **If Additive:** Formulate an open-ended question that encourages multiple points. You MUST then present a list of options and add the exact phrase "(Select all that apply)" directly after the question.
232 |             *   **If Exclusive Choice:** Formulate a direct question that guides the user to a single, clear decision. You MUST NOT add "(Select all that apply)".
233 | 
234 |         *   **3. Interaction Flow:**
235 |                 *   **CRITICAL:** You MUST ask questions sequentially (one by one). Do not ask multiple questions in a single turn. Wait for the user's response after each question.
236 |             *   The last two options for every multiple-choice question MUST be "Type your own answer" and "Autogenerate and review tech-stack.md".
237 |             *   Confirm your understanding by summarizing before moving on.
238 |         - **Format:** You MUST present these as a vertical list, with each option on its own line.
239 |         - **Structure:**
240 |             A) [Option A]
241 |             B) [Option B]
242 |             C) [Option C]
243 |             D) [Type your own answer]
244 |             E) [Autogenerate and review tech-stack.md]
245 |     -   **FOR EXISTING PROJECTS (BROWNFIELD):**
246 |             -   **CRITICAL WARNING:** Your goal is to document the project's *existing* tech stack, not to propose changes.
247 |             -   **State the Inferred Stack:** Based on the code analysis, you MUST state the technology stack that you have inferred. Do not present any other options.
248 |             -   **Request Confirmation:** After stating the detected stack, you MUST ask the user for a simple confirmation to proceed with options like:
249 |                 A) Yes, this is correct.
250 |                 B) No, I need to provide the correct tech stack.
251 |             -   **Handle Disagreement:** If the user disputes the suggestion, acknowledge their input and allow them to provide the correct technology stack manually as a last resort.
252 |     -   **AUTO-GENERATE LOGIC:** If the user selects option E, immediately stop asking questions for this section. Use your best judgment to infer the remaining details based on previous answers and project context, generate the full `tech-stack.md` content, write it to the file, and proceed to the next section.
253 | 3.  **Draft the Document:** Once the dialogue is complete (or option E is selected), generate the content for `tech-stack.md`. If option E was chosen, use your best judgment to infer the remaining details based on previous answers and project context. You are encouraged to expand on the gathered details to create a comprehensive document.
254 |     -   **CRITICAL:** The source of truth for generation is **only the user's selected answer(s)**. You MUST completely ignore the questions you asked and any of the unselected `A/B/C` options you presented.
255 |     -   **Action:** Take the user's chosen answer and synthesize it into a well-formed section for the document. You are encouraged to expand on the user's choice to create a comprehensive and polished output. DO NOT include the conversational options (A, B, C, D, E) in the final file.
256 | 4.  **User Confirmation Loop:** Present the drafted content to the user for review and begin the confirmation loop.
257 |     > "I've drafted the tech stack document. Please review the following:"
258 |     >
259 |     > ```markdown
260 |     > [Drafted tech-stack.md content here]
261 |     > ```
262 |     >
263 |     > "What would you like to do next?
264 |     > A) **Approve:** The document is correct and we can proceed.
265 |     > B) **Suggest Changes:** Tell me what to modify.
266 |     >
267 |     > You can always edit the generated file with the Gemini CLI built-in option "Modify with external editor" (if present), or with your favorite external editor after this step.
268 |     > Please respond with A or B."
269 |     - **Loop:** Based on user response, either apply changes and re-present the document, or break the loop on approval.
270 | 6.  **Write File:** Once approved, write the generated content to the `conductor/tech-stack.md` file.
271 | 7.  **Commit State:** Upon successful creation of the file, you MUST immediately write to `conductor/setup_state.json` with the exact content:
272 |     `{"last_successful_step": "2.3_tech_stack"}`
273 | 8.  **Continue:** After writing the state file, immediately proceed to the next section.
274 | 
275 | ### 2.4 Select Guides (Interactive)
276 | 1.  **Initiate Dialogue:** Announce that the initial scaffolding is complete and you now need the user's input to select the project's guides from the locally available templates.
277 | 2.  **Select Code Style Guides:**
278 |     -   List the available style guides by running `ls ~/.gemini/extensions/conductor/templates/code_styleguides/`.
279 |     -   For new projects (greenfield):
280 |         -   **Recommendation:** Based on the Tech Stack defined in the previous step, recommend the most appropriate style guide(s) and explain why.
281 |         -   Ask the user how they would like to proceed:
282 |             A) Include the recommended style guides.
283 |             B) Edit the selected set.
284 |         -   If the user chooses to edit (Option B):
285 |             -   Present the list of all available guides to the user as a **numbered list**.
286 |             -   Ask the user which guide(s) they would like to copy.
287 |     -   For existing projects (brownfield):
288 |         -   **Announce Selection:** Inform the user: "Based on the inferred tech stack, I will copy the following code style guides: <list of inferred guides>."
289 |         -   **Ask for Customization:** Ask the user: "Would you like to proceed using only the suggested code style guides?"
290 |             - Ask the user for a simple confirmation to proceed with options like:
291 |                     A) Yes, I want to proceed with the suggested code style guides.
292 |                     B) No, I want to add more code style guides.
293 |     -   **Action:** Construct and execute a command to create the directory and copy all selected files. For example: `mkdir -p conductor/code_styleguides && cp ~/.gemini/extensions/conductor/templates/code_styleguides/python.md ~/.gemini/extensions/conductor/templates/code_styleguides/javascript.md conductor/code_styleguides/`
294 |     -   **Commit State:** Upon successful completion of the copy command, you MUST immediately write to `conductor/setup_state.json` with the exact content:
295 |         `{"last_successful_step": "2.4_code_styleguides"}`
296 | 
297 | ### 2.5 Select Workflow (Interactive)
298 | 1.  **Copy Initial Workflow:**
299 |     -   Copy `~/.gemini/extensions/conductor/templates/workflow.md` to `conductor/workflow.md`.
300 | 2.  **Customize Workflow:**
301 |     -   Ask the user: "Do you want to use the default workflow or customize it?"
302 |         The default workflow includes:
303 |          - 80% code test coverage
304 |          - Commit changes after every task
305 |          - Use Git Notes for task summaries
306 |         -   A) Default
307 |         -   B) Customize
308 |     -   If the user chooses to **customize** (Option B):
309 |         -   **Question 1:** "The default required test code coverage is >80% (Recommended). Do you want to change this percentage?"
310 |             -   A) No (Keep 80% required coverage)
311 |             -   B) Yes (Type the new percentage)
312 |         -   **Question 2:** "Do you want to commit changes after each task or after each phase (group of tasks)?"
313 |             -   A) After each task (Recommended)
314 |             -   B) After each phase
315 |         -   **Question 3:** "Do you want to use git notes or the commit message to record the task summary?"
316 |             -   A) Git Notes (Recommended)
317 |             -   B) Commit Message
318 |         -   **Action:** Update `conductor/workflow.md` based on the user's responses.
319 |         -   **Commit State:** After the `workflow.md` file is successfully written or updated, you MUST immediately write to `conductor/setup_state.json` with the exact content:
320 |             `{"last_successful_step": "2.5_workflow"}`
321 | 
322 | ### 2.6 Finalization
323 | 1.  **Summarize Actions:** Present a summary of all actions taken during Phase 1, including:
324 |     -   The guide files that were copied.
325 |     -   The workflow file that was copied.
326 | 2.  **Transition to initial plan and track generation:** Announce that the initial setup is complete and you will now proceed to define the first track for the project.
327 | 
328 | ---
329 | 
330 | ## 3.0 INITIAL PLAN AND TRACK GENERATION
331 | **PROTOCOL: Interactively define project requirements, propose a single track, and then automatically create the corresponding track and its phased plan.**
332 | 
333 | ### 3.1 Generate Product Requirements (Interactive)(For greenfield projects only)
334 | 1.  **Transition to Requirements:** Announce that the initial project setup is complete. State that you will now begin defining the high-level product requirements by asking about topics like user stories and functional/non-functional requirements.
335 | 2.  **Analyze Context:** Read and analyze the content of `conductor/product.md` to understand the project's core concept.
336 | 3.  **Ask Questions Sequentially:** Ask one question at a time. Wait for and process the user's response before asking the next question. Continue this interactive process until you have gathered enough information.
337 |     -   **CONSTRAINT** Limit your inquiries to a maximum of 5 questions.
338 |     -   **SUGGESTIONS:** For each question, generate 3 high-quality suggested answers based on common patterns or context you already have.
339 |     *   **General Guidelines:**
340 |         *   **1. Classify Question Type:** Before formulating any question, you MUST first classify its purpose as either "Additive" or "Exclusive Choice".
341 |             *   Use **Additive** for brainstorming and defining scope (e.g., users, goals, features, project guidelines). These questions allow for multiple answers.
342 |             *   Use **Exclusive Choice** for foundational, singular commitments (e.g., selecting a primary technology, a specific workflow rule). These questions require a single answer.
343 | 
344 |         *   **2. Formulate the Question:** Based on the classification, you MUST adhere to the following:
345 |             *   **If Additive:** Formulate an open-ended question that encourages multiple points. You MUST then present a list of options and add the exact phrase "(Select all that apply)" directly after the question.
346 |             *   **If Exclusive Choice:** Formulate a direct question that guides the user to a single, clear decision. You MUST NOT add "(Select all that apply)".
347 | 
348 |         *   **3. Interaction Flow:**
349 |                 *   **CRITICAL:** You MUST ask questions sequentially (one by one). Do not ask multiple questions in a single turn. Wait for the user's response after each question.
350 |             *   The last two options for every multiple-choice question MUST be "Type your own answer" and "Auto-generate the rest of requirements and move to the next step".
351 |             *   Confirm your understanding by summarizing before moving on.
352 |         - **Format:** You MUST present these as a vertical list, with each option on its own line.
353 |         - **Structure:**
354 |             A) [Option A]
355 |             B) [Option B]
356 |             C) [Option C]
357 |             D) [Type your own answer]
358 |             E) [Auto-generate the rest of requirements and move to the next step]
359 |     -   **AUTO-GENERATE LOGIC:** If the user selects option E, immediately stop asking questions for this section. Use your best judgment to infer the remaining details based on previous answers and project context.
360 | -   **CRITICAL:** When processing user responses or auto-generating content, the source of truth for generation is **only the user's selected answer(s)**. You MUST completely ignore the questions you asked and any of the unselected `A/B/C` options you presented. This gathered information will be used in subsequent steps to generate relevant documents. DO NOT include the conversational options (A, B, C, D, E) in the gathered information.
361 | 4.  **Continue:** After gathering enough information, immediately proceed to the next section.
362 | 
363 | ### 3.2 Propose a Single Initial Track (Automated + Approval)
364 | 1.  **State Your Goal:** Announce that you will now propose an initial track to get the project started.
365 | 2.  **Generate Track Title:** Analyze the project context (`product.md`, `tech-stack.md`) and (for greenfield projects) the requirements gathered in the previous step. Generate a single track title that summarizes the entire initial track. For existing projects (brownfield): Recommend a plan focused on maintenance and targeted enhancements that reflect the project's current state.
366 |     - Greenfield project example (usually MVP):
367 |         ```markdown
368 |         To create the MVP of this project, I suggest the following track:
369 |         - Build the core functionality for the tip calculator with a basic calculator and built-in tip percentages.
370 |         ```
371 |     - Brownfield project example:
372 |         ```markdown
373 |         To create the first track of this project, I suggest the following track:
374 |         - Create user authentication flow for user sign in.
375 |         ```
376 | 3.  **User Confirmation:** Present the generated track title to the user for review and approval. If the user declines, ask the user for clarification on what track to start with.
377 | 
378 | ### 3.3 Convert the Initial Track into Artifacts (Automated)
379 | 1.  **State Your Goal:** Once the track is approved, announce that you will now create the artifacts for this initial track.
380 | 2.  **Initialize Tracks File:** Create the `conductor/tracks.md` file with the initial header and the first track:
381 |     ```markdown
382 |     # Project Tracks
383 | 
384 |     This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
385 | 
386 |     ---
387 | 
388 |     ## [ ] Track: <Track Description>
389 |     *Link: [./conductor/tracks/<track_id>/](./conductor/tracks/<track_id>/)*
390 |     ```
391 | 3.  **Generate Track Artifacts:**
392 |     a. **Define Track:** The approved title is the track description.
393 |     b. **Generate Track-Specific Spec & Plan:**
394 |         i. Automatically generate a detailed `spec.md` for this track.
395 |         ii. Automatically generate a `plan.md` for this track.
396 |             - **CRITICAL:** The structure of the tasks must adhere to the principles outlined in the workflow file at `conductor/workflow.md`. For example, if the workflow specificies Test-Driven Development, each feature task must be broken down into a "Write Tests" sub-task followed by an "Implement Feature" sub-task.
397 |             - **CRITICAL: Inject Phase Completion Tasks.** You MUST read the `conductor/workflow.md` file to determine if a "Phase Completion Verification and Checkpointing Protocol" is defined. If this protocol exists, then for each **Phase** that you generate in `plan.md`, you MUST append a final meta-task to that phase. The format for this meta-task is: `- [ ] Task: Conductor - User Manual Verification '<Phase Name>' (Protocol in workflow.md)`. You MUST replace `<Phase Name>` with the actual name of the phase.
398 |     c. **Create Track Artifacts:**
399 |         i. **Generate and Store Track ID:** Create a unique Track ID from the track description using format `shortname_YYYYMMDD` and store it. You MUST use this exact same ID for all subsequent steps for this track.
400 |         ii. **Create Single Directory:** Using the stored Track ID, create a single new directory: `conductor/tracks/<track_id>/`.
401 |         iii. **Create `metadata.json`:** In the new directory, create a `metadata.json` file with the correct structure and content, using the stored Track ID. An example is:
402 |             - ```json
403 |             {
404 |             "track_id": "<track_id>",
405 |             "type": "feature", // or "bug"
406 |             "status": "new", // or in_progress, completed, cancelled
407 |             "created_at": "YYYY-MM-DDTHH:MM:SSZ",
408 |             "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
409 |             "description": "<Initial user description>",
410 |             }
411 |             ```
412 |         Populate fields with actual values. Use the current timestamp.
413 |         iv. **Write Spec and Plan Files:** In the exact same directory, write the generated `spec.md` and `plan.md` files.
414 | 
415 |     d. **Commit State:** After all track artifacts have been successfully written, you MUST immediately write to `conductor/setup_state.json` with the exact content:
416 |        `{"last_successful_step": "3.3_initial_track_generated"}`
417 | 
418 |     e. **Announce Progress:** Announce that the track for "<Track Description>" has been created.
419 | 
420 | ### 3.4 Final Announcement
421 | 1.  **Announce Completion:** After the track has been created, announce that the project setup and initial track generation are complete.
422 | 2.  **Save Conductor Files:** Add and commit all files with the commit message `conductor(setup): Add conductor setup files`.
423 | 3.  **Next Steps:** Inform the user that they can now begin work by running `/conductor:implement`.
424 | """


--------------------------------------------------------------------------------