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