Add conductor setup files
This is required to use the AI development tool conductor with GN.
These files were automatically generated via conductor asking me a bunch
of questions and having me respond. I then reviewed all the files and
manually edited things I didn't like.
Change-Id: I3a13f02645ad0552602e2420fbc045806a6a6964
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/20800
Reviewed-by: Takuto Ikuta <tikuta@google.com>
Commit-Queue: Matt Stark <msta@google.com>
diff --git a/conductor/README.md b/conductor/README.md
new file mode 100644
index 0000000..720287e
--- /dev/null
+++ b/conductor/README.md
@@ -0,0 +1,5 @@
+Conductor (https://github.com/gemini-cli-extensions/conductor) is a Gemini CLI
+extension to better support working on brownfield projects.
+
+This directory is required to use conductor, and tells it everything it needs
+to know about how to work on GN.
\ No newline at end of file
diff --git a/conductor/code_styleguides/general.md b/conductor/code_styleguides/general.md
new file mode 100644
index 0000000..dfcc793
--- /dev/null
+++ b/conductor/code_styleguides/general.md
@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.
diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md
new file mode 100644
index 0000000..285b469
--- /dev/null
+++ b/conductor/code_styleguides/python.md
@@ -0,0 +1,37 @@
+# Google Python Style Guide Summary
+
+This document summarizes key rules and best practices from the Google Python Style Guide.
+
+## 1. Python Language Rules
+- **Linting:** Run `pylint` on your code to catch bugs and style issues.
+- **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule.
+- **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses.
+- **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`.
+- **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable.
+- **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values.
+- **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`.
+- **Type Annotations:** Strongly encouraged for all public APIs.
+
+## 2. Python Style Rules
+- **Line Length:** Maximum 80 characters.
+- **Indentation:** 4 spaces per indentation level. Never use tabs.
+- **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions.
+- **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces.
+- **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring.
+ - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections.
+- **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes.
+- **`TODO` Comments:** Use `TODO(username): Fix this.` format.
+- **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports.
+
+## 3. Naming
+- **General:** `snake_case` for modules, functions, methods, and variables.
+- **Classes:** `PascalCase`.
+- **Constants:** `ALL_CAPS_WITH_UNDERSCORES`.
+- **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members.
+
+## 4. Main
+- All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block.
+
+**BE CONSISTENT.** When editing code, match the existing style.
+
+*Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)*
\ No newline at end of file
diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md
new file mode 100644
index 0000000..b601c39
--- /dev/null
+++ b/conductor/product-guidelines.md
@@ -0,0 +1,9 @@
+# Product Guidelines
+
+## Prose Style
+
+All documentation and user-facing messages should be concise and direct. Language should be clear and to the point, avoiding unnecessary jargon or overly casual phrasing.
+
+## Branding and Visual Identity
+
+There are no specific branding or visual identity guidelines to adhere to at this time.
diff --git a/conductor/product.md b/conductor/product.md
new file mode 100644
index 0000000..9371a9a
--- /dev/null
+++ b/conductor/product.md
@@ -0,0 +1,11 @@
+# Initial Concept
+GN is a meta-build system that generates build files for Ninja.
+
+# Primary Goals (Next 1-3 Months)
+
+- See "Key feature priorities"
+
+# Key Feature Priorities
+
+- Add support for C++ standard modules.
+- Add support for a binary ninja file format that can be quickly parsed.
diff --git a/conductor/setup_state.json b/conductor/setup_state.json
new file mode 100644
index 0000000..1be6908
--- /dev/null
+++ b/conductor/setup_state.json
@@ -0,0 +1 @@
+{"last_successful_step": "2.4_code_styleguides"}
\ No newline at end of file
diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md
new file mode 100644
index 0000000..ecfb921
--- /dev/null
+++ b/conductor/tech-stack.md
@@ -0,0 +1,15 @@
+# Technology Stack
+
+## Primary Language
+
+* **C++:** The core GN tool is written in C++.
+
+## Build System
+* The script `build/gen.py` regenerates ninja files.
+* It generates two relevant targets - `gn` and `gn_unittests`
+* Examples from the `examples` directory can be built with `gn gen` and then ran with `ninja`
+* For the ultimate test of whether it works, you can use `gn` on a chromium checkout.
+
+## Scripting
+
+* Scripting is done in either python or shell, whichever is easier.
diff --git a/conductor/workflow.md b/conductor/workflow.md
new file mode 100644
index 0000000..d257954
--- /dev/null
+++ b/conductor/workflow.md
@@ -0,0 +1,215 @@
+# Project Workflow
+
+## Guiding Principles
+
+1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md`
+2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation
+3. **Test-Driven Development:** Write unit tests before implementing functionality
+4. **High Code Coverage:** Aim for >80% code coverage for all modules
+5. **User Experience First:** Every decision should prioritize user experience
+6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
+
+## Task Workflow
+
+All tasks follow a strict lifecycle:
+
+### Standard Task Workflow
+
+1. **Select Task:** Choose the next available task from `plan.md` in sequential order
+
+2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
+
+3. **Write Failing Tests (Red Phase):**
+ - Create a new test file for the feature or bug fix.
+ - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
+ - **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.
+
+4. **Implement to Pass Tests (Green Phase):**
+ - Write the minimum amount of application code necessary to make the failing tests pass.
+ - Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
+
+5. **Refactor (Optional but Recommended):**
+ - 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.
+ - Rerun tests to ensure they still pass after refactoring.
+
+6. **Document Deviations:** If implementation differs from tech stack:
+ - **STOP** implementation
+ - Update `tech-stack.md` with new design
+ - Add dated note explaining the change
+ - Resume implementation
+
+7. **Commit Code Changes:**
+ - Stage all code changes related to the task.
+ - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`.
+ - Perform the commit.
+
+8. **Attach Task Summary with Git Notes:**
+ - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
+ - **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.
+ - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
+ ```bash
+ # The note content from the previous step is passed via the -m flag.
+ git notes add -m "<note content>" <commit_hash>
+ ```
+
+9. **Get and Record Task Commit SHA:**
+ - **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.
+ - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`.
+
+10. **Commit Plan Update:**
+ - **Action:** Stage the modified `plan.md` file.
+ - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`).
+
+### Phase Completion Verification and Checkpointing Protocol
+
+**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
+
+1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
+
+2. **Ensure Test Coverage for Phase Changes:**
+ - **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.
+ - **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.
+ - **Step 2.3: Verify and Create Tests:** For each file in the list:
+ - **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`).
+ - For each remaining code file, verify a corresponding test file exists.
+ - 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`).
+
+3. **Execute Automated Tests with Proactive Debugging:**
+ - Before execution, you **must** announce the exact shell command you will use to run the tests.
+ - **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`"
+ - Execute the announced command.
+ - 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.
+
+4. **Propose a Detailed, Actionable Manual Verification Plan:**
+ - **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.
+ - You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes.
+ - The plan you present to the user **must** follow this format:
+
+ **For a Frontend Change:**
+ ```
+ The automated tests have passed. For manual verification, please follow these steps:
+
+ **Manual Verification Steps:**
+ 1. **Start the development server with the command:** `npm run dev`
+ 2. **Open your browser to:** `http://localhost:3000`
+ 3. **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly.
+ ```
+
+ **For a Backend Change:**
+ ```
+ The automated tests have passed. For manual verification, please follow these steps:
+
+ **Manual Verification Steps:**
+ 1. **Ensure the server is running.**
+ 2. **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
+ 3. **Confirm that you receive:** A JSON response with a status of `201 Created`.
+ ```
+
+5. **Await Explicit User Feedback:**
+ - 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.**"
+ - **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation.
+
+6. **Create Checkpoint Commit:**
+ - Stage all changes. If no changes occurred in this step, proceed with an empty commit.
+ - Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`).
+
+7. **Attach Auditable Verification Report using Git Notes:**
+ - **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.
+ - **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.
+
+8. **Get and Record Phase Checkpoint SHA:**
+ - **Step 7.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`).
+ - **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>]`.
+ - **Step 7.3: Write Plan:** Write the updated content back to `plan.md`.
+
+9. **Commit Plan Update:**
+ - **Action:** Stage the modified `plan.md` file.
+ - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
+
+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.
+
+### Quality Gates
+
+Before marking any task complete, verify:
+
+- [ ] All tests pass
+- [ ] Code coverage meets requirements (>80%)
+- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`)
+- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc)
+- [ ] No linting or static analysis errors (using the project's configured tools)
+- [ ] Documentation updated if needed
+
+## Development Commands
+* Building: `./gen.py && ninja -C out $TARGETS`, where targets can be `gn` or `gn_unittests` for the tool or the tests respectively.
+* Running tests: `out/gn_unittests`
+ * It uses a gtest-like framework defined in `util/test/test.h` so you can use standard gtest filters to only run specific tests.
+
+### Setup
+
+## Testing Requirements
+
+### Unit Testing
+- Every module must have corresponding tests.
+- Follow existing test styles.
+
+## Code Review Process
+
+### Self-Review Checklist
+Before requesting review:
+
+1. **Functionality**
+ - Feature works as specified
+ - Edge cases handled
+ - Error messages are user-friendly
+
+2. **Code Quality**
+ - Follows style guide
+ - DRY principle applied
+ - Clear variable/function names
+ - Appropriate comments
+
+3. **Testing**
+ - Unit tests comprehensive
+ - Integration tests pass
+
+## Commit Guidelines
+
+### Message Format
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, missing semicolons, etc.
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests
+- `chore`: Maintenance tasks
+
+### Examples
+```bash
+git commit -m "feat(auth): Add remember me functionality"
+git commit -m "fix(posts): Correct excerpt generation for short posts"
+git commit -m "test(comments): Add tests for emoji reaction limits"
+git commit -m "style(mobile): Improve button touch targets"
+```
+
+## Definition of Done
+
+A task is complete when:
+
+1. All code implemented to specification
+2. Unit tests written and passing
+3. Code coverage meets project requirements
+4. Documentation complete (if applicable)
+5. Code passes all configured linting and static analysis checks
+6. Works beautifully on mobile (if applicable)
+7. Implementation notes added to `plan.md`
+8. Changes committed with proper message
+9. Git note with task summary attached to the commit
