Feature/add documentation and copilot instructions#9
Conversation
…ation and guidelines - Introduced SECURITY.md for reporting vulnerabilities and response processes. - Updated README.md in agent1 to reflect new command syntax for running agents and checks. - Modified pyproject.toml to include additional targets for security checks and exclude unnecessary directories. - Enhanced agent guide documentation with updated command usage. - Created __init__.py in docs/source to facilitate documentation generation. - Improved conf.py for version retrieval and added support for sphinx_autodoc_typehints. - Updated scripts for documentation generation to handle errors more gracefully and improve logging. - Refactored task execution scripts to enforce minimum argument requirements and improve subprocess handling. - Removed outdated bandit command from shared_tasks.toml.
There was a problem hiding this comment.
Pull request overview
This PR strengthens repository standards and developer onboarding by adding contribution/documentation guidance, VS Code workspace defaults, and expanding repo-wide automation for formatting/linting/type-checking/docs.
Changes:
- Added repository policy/docs (CONTRIBUTING, DEVELOPMENT, CODING_STANDARDS, SECURITY, CODE_OF_CONDUCT) plus GitHub templates (issues + PR).
- Expanded root tooling: updated Poe tasks, Bandit/Ruff/Pyright usage, and improved scripts for docs generation and markdown code-block linting.
- Added VS Code workspace configuration (tasks, launch, settings, extension recommendations).
Reviewed changes
Copilot reviewed 28 out of 29 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| shared_tasks.toml | Adjusts shared Poe task definitions used by agents. |
| scripts/utils/task_utils.py | Minor cleanup in task discovery helpers. |
| scripts/run_tasks_in_changed_agents.py | Tightens subprocess lint suppressions and formatting for changed-agent task runner. |
| scripts/run_tasks_in_agents_if_exists.py | Adds a constant for argv length check; minor cleanup. |
| scripts/generate_docs.py | Improves typing, logging, and subprocess lint suppression for Sphinx builds. |
| scripts/check_md_code_blocks.py | Extends markdown Python-fence checking to run both Pyright and Ruff. |
| pyproject.toml | Updates Ruff/Bandit config and refactors root Poe tasks (fmt/lint/pyright/mypy/bandit/markdown lint). |
| docs/source/conf.py | Minor formatting cleanup in Sphinx config. |
| docs/manual/agent-guide-template.md | Updates uv invocation examples for running agents/tasks from repo root. |
| agents/agent1/pyproject.toml | Expands Bandit targets and adjusts agent task overrides accordingly. |
| agents/agent1/README.md | Updates repo-root run examples to the new uv invocation patterns. |
| SECURITY.md | Adds a security policy and reporting process. |
| DEVELOPMENT.md | Adds a comprehensive development setup and workflow guide. |
| CONTRIBUTING.md | Adds contribution guidelines and workflow. |
| CODING_STANDARDS.md | Adds detailed coding/testing/style standards for the repo. |
| CODE_OF_CONDUCT.md | Adds Contributor Covenant Code of Conduct. |
| .vscode/tasks.json | Adds VS Code tasks for common workflows (check/fmt/lint/typecheck/test/setup). |
| .vscode/settings.json | Adds VS Code settings for Ruff + Python analysis defaults. |
| .vscode/launch.json | Adds debug configurations for current file + attach. |
| .vscode/extensions.json | Recommends key extensions (Python/Pylance/Ruff/Spell checker). |
| .pre-commit-config.yaml | Expands pre-commit scope to include .github/instructions/*.md. |
| .github/pull_request_template.md | Adds a PR template for consistent submissions. |
| .github/instructions/python.instructions.md | Adds Copilot instructions for Python files. |
| .github/instructions/docs.instructions.md | Adds Copilot instructions for docs files. |
| .github/instructions/agents.instructions.md | Adds Copilot instructions for agent packages. |
| .github/copilot-instructions.md | Adds overall Copilot/project guidance. |
| .github/ISSUE_TEMPLATE/feature_request.yml | Adds a structured feature request issue form. |
| .github/ISSUE_TEMPLATE/bug_report.yml | Adds a structured bug report issue form. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Changed "Syntax errors found" to "Type checking or linting issues found" to accurately reflect that the script checks for Pyright (type checking) and Ruff (linting) issues, not just syntax errors. Co-authored-by: pmalarme <686568+pmalarme@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…settings Co-authored-by: pmalarme <686568+pmalarme@users.noreply.github.com>
Updated the module docstring to reflect "type checking and linting issues" instead of "syntax errors" to match the updated error message and actual behavior of the script. Co-authored-by: pmalarme <686568+pmalarme@users.noreply.github.com>
Co-authored-by: pmalarme <686568+pmalarme@users.noreply.github.com>
Co-authored-by: pmalarme <686568+pmalarme@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 29 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Fix error message in check_md_code_blocks.py to reflect type/lint checks
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Add cross-platform Python interpreter path for VS Code
Fix shared_tasks.toml check sequence referencing undefined tasks
Address review comment: Explain strict parameter in zip() call
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 29 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 29 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
pmalarme
deleted the
feature/add-documentation-and-copilot-instructions
branch
|
|
||
| ## Development Guide | ||
|
|
||
| This guide explains how to work on the repo, run agents, and perform common tasks. It also provides a section to explains how to work with VS Code. |
There was a problem hiding this comment.
Minor grammar: “provides a section to explains” should be “provides a section to explain” (or similar).
| This guide explains how to work on the repo, run agents, and perform common tasks. It also provides a section to explains how to work with VS Code. | |
| This guide explains how to work on the repo, run agents, and perform common tasks. It also provides a section to explain how to work with VS Code. |
| - **DON'T** be discouraged if your pull request is not accepted immediately. The maintainers may request changes or provide feedback to help improve your contribution. | ||
| - **DON'T** submit pull requests without an issue. If there is no issue, please create one first to discuss your proposed changes. | ||
| - **DON'T** include proprietary or third-party code in your pull request without proper authorization and without prior discussion with the maintainers. | ||
| - **DON'T** push code you didn't write yourself. Always ensure you have the right to submit the code you are contributing. |
There was a problem hiding this comment.
Wording is duplicated here (“DON'T don't push …”). Drop the second “don't” so the bullet reads cleanly.
| ## Additional context | ||
|
|
||
| <!-- Optional: screenshots, logs, deployment notes. --> | ||
| - |
There was a problem hiding this comment.
The template ends with a lone - list item, which renders as an empty bullet in PR descriptions. Consider removing it or replacing it with a placeholder comment so the section doesn’t show an empty list item by default.
| - |
| - `agents/`: multiple agent packages | ||
| - `agents/<agent>/src/python_agent_template/agents/<agent>/`: agent code | ||
| - `agents/<agent>/tests/`: agent tests | ||
| - `agents/<agent>/docs/`: agent docs (`source/` for inputs, `generated/` for outputs)` |
There was a problem hiding this comment.
There’s an extra trailing backtick at the end of this bullet, which breaks the intended inline-code formatting in Markdown. Remove the final backtick so the parentheses/text render correctly.
| - `agents/<agent>/docs/`: agent docs (`source/` for inputs, `generated/` for outputs)` | |
| - `agents/<agent>/docs/`: agent docs (`source/` for inputs, `generated/` for outputs) |
| "label": "Mypy", | ||
| "type": "shell", | ||
| "command": "uv", | ||
| "detail": "Mypy strict type check (agents + scripts + docs)", |
There was a problem hiding this comment.
The task detail says Mypy checks “agents + scripts + docs”, but the root mypy task (mypy-root = "uv run mypy --config-file pyproject.toml") currently only checks the packages configured under [tool.mypy] (agents + scripts). Update this description (or expand mypy’s configured targets) so VS Code task output matches what actually runs.
| "detail": "Mypy strict type check (agents + scripts + docs)", | |
| "detail": "Mypy strict type check (agents + scripts)", |
| highlighted_code, | ||
| with_color(f"{tool_name.lower()} output:", Colors.CVIOLET), | ||
| with_color(result.stdout, Colors.CRED), | ||
| with_color("========================================================", Colors.CGREY), |
There was a problem hiding this comment.
When a tool fails, the log output only includes result.stdout. Both Pyright and Ruff can emit important diagnostics to stderr (e.g., config/usage errors), so failures can be hard to debug. Consider including result.stderr (and/or combining stdout+stderr) in the reported output.
This pull request introduces several improvements to project documentation, developer workflow, and repository standards. The main changes include adding new issue templates, a pull request template, a code of conduct, comprehensive project instructions, and enhanced VSCode configuration files. These updates aim to standardize contributions, clarify development practices, and improve onboarding and collaboration for all contributors.
Repository Standards and Contribution Process
.github/ISSUE_TEMPLATE/bug_report.ymland.github/ISSUE_TEMPLATE/feature_request.ymlto standardize bug reports and feature requests, ensuring all necessary information is collected for triage and resolution. [1] [2].github/pull_request_template.mdto guide contributors in summarizing changes, testing, and compliance with project requirements during pull requests.CODE_OF_CONDUCT.mdto establish clear community guidelines and enforcement procedures for contributor interactions.Project Documentation and Developer Guidance
.github/copilot-instructions.mdand specialized instructions files for agents, documentation, and Python code, providing clear guidelines on code quality, security, documentation, and workflow for different parts of the repository. [1] [2] [3] [4].pre-commit-config.yamlto include the new instructions files in pre-commit checks, ensuring documentation and standards are maintained.VSCode Environment and Workflow Enhancements
.vscode/extensions.json,.vscode/launch.json,.vscode/settings.json, and.vscode/tasks.jsonto recommend extensions, configure debugging, enforce formatting/linting, and provide common tasks for quality checks, improving the developer experience for VSCode users. [1] [2] [3] [4]