Skip to content

Latest commit

 

History

History
171 lines (117 loc) · 7.12 KB

AGENTS.md

File metadata and controls

171 lines (117 loc) · 7.12 KB

AGENTS.md

Project overview

This repository is a small Python setup for starting python developer as quickly as possible using a devcontainer and AI assisted workflows.

The current runtime entrypoint is a minimal script that loads environment variables from a .env file (via python-dotenv) and prints whether anything was loaded.

Repo layout

  • src/app.py: entrypoint; calls load_env()
  • src/load_env.py: .env discovery + python-dotenv loading
  • pyproject.toml: Python project metadata + dependencies (managed by uv)
  • uv.lock: resolved dependency lockfile (generated by uv)
  • .env-sample: example environment variables (copy to .env)

Setup

Install uv

This template uses uv for dependency management and virtualenv creation.

  • Install (Linux/macOS):
curl -LsSf https://astral.sh/uv/install.sh | sh

If uv is installed during devcontainer creation, you may need to restart the terminal so uv is on your PATH.

Create a virtual environment + install dependencies

uv sync

Environment variables

  • Copy .env-sample to .env and fill in real values.
  • .env is gitignored (see .gitignore).
cp .env-sample .env

Development workflow

Run the app

From the repository root:

uv run python src/app.py

Notes about .env discovery:

  • src/load_env.py checks for .env in the current working directory (.env) and one level up (../.env).
  • If you run from the repo root, put .env in the repo root.
  • If you run from src/, it will also find the repo-root .env via ../.env.

Copilot / AI Assisted workflow

  • All Copilot and AI assisted workflows exist in the .agent directory
  • If the user asks about workflows, prompts or other AI assisted ways of working, describe the use and structure of the .agent directory and purpose.
  • Github Copilot CLI and Teambot are also pre-installed for use on agentic workflows.
  • To start using Copilot CLI, type copilot
  • To start using Teambot, you must:
    • First ensure you have logged in via copilot using `/login'
    • Run teambot init to set up templates and workflows.
    • Then run teambot run to begin using.

.agent directory structure

The .agent directory contains commands, instructions, and standards used by AI-assisted workflows.

Commands (commands/)

Prompt files invoked as slash commands (e.g. /sdd:0-initialize).

Path Description
commands/azdo/azdo.generate-pr-description.prompt.md Generates pull request descriptions using Azure DevOps templates.
commands/docs/docs.create-adr.prompt.md Creates architecture decision records following organisational standards.
commands/project/proj.sprint-planning.prompt.md Builds sprint plans for software engineering teams to deliver implementation engagements.
commands/setup/setup.agents-md-creation.prompt.md Generates or updates the AGENTS.md file for the repository.

Spec-Driven Development (SDD) workflow (commands/sdd/)

A sequential workflow with quality gates for taking a feature from specification through to implementation.

Path Description
commands/sdd/README.md Documents the SDD workflow overview and its 9 sequential steps.
commands/sdd/sdd.0-initialize.prompt.md Initialises the SDD workflow by verifying prerequisites and creating tracking directories.
commands/sdd/sdd.1-create-feature-spec.prompt.md Guides creation of feature specifications with Q&A and reference integration.
commands/sdd/sdd.2-review-spec.prompt.md Reviews and validates specifications before the research phase.
commands/sdd/sdd.3-research-feature.prompt.md Conducts comprehensive research and analysis for the feature.
commands/sdd/sdd.4-determine-test-strategy.prompt.md Analyses specs and research to recommend an optimal testing strategy.
commands/sdd/sdd.5-task-planner-for-feature.prompt.md Creates actionable implementation plans for the feature.
commands/sdd/sdd.6-review-plan.prompt.md Reviews and validates implementation plans before execution.
commands/sdd/sdd.7-task-implementer-for-feature.prompt.md Implements task plans with progressive tracking and change records.
commands/sdd/sdd.8-post-implementation-review.prompt.md Performs post-implementation review and final validation.

Instructions (instructions/)

Contextual guidelines automatically applied to AI interactions.

Path Description
instructions/prompt.instructions.md Guidelines for creating high-quality prompt files for GitHub Copilot.
instructions/bash/bash.instructions.md Instructions for bash script implementation with established conventions.
instructions/bash/bash.md Guidelines for secure, maintainable bash scripting practices.
instructions/bicep/bicep-standards.md Coding standards and best practices for Bicep Infrastructure as Code.
instructions/bicep/bicep.instructions.md Instructions for Bicep infrastructure implementation.
instructions/bicep/bicep.md Structural guidelines for Bicep development.

Standards (standards/)

Templates and standards referenced by commands and instructions.

Path Description
standards/decision-record-standards.md Standards for creating decision records capturing architectural and policy decisions.
standards/decision-record-template.md Template for decision records with status, deciders, context, and consequences.
standards/feature-spec-template.md Template for feature specification documents with progress tracking.
standards/research-feature-template.md Template for task research documents with implementation analysis.
standards/task-planning-template.md Template for task checklists with overview and implementation instructions.

Add new scripts

If you add more Python modules under src/, running them as python3 src/<script>.py from the repo root will generally keep imports simple.

If you want python -m ... module execution, add src/__init__.py and switch to package-style imports.

Testing

  • Framework: pytest with pytest-cov and pytest-mock
  • Tests located in tests/ directory
  • Current coverage: 80% (1050 tests)

Linting and formatting

This template includes ruff as the default linter/formatter.

uv sync --group dev
uv run ruff check .
uv run ruff format .

Clean commits

  • When committing or changing code, always ensure properly linted code by running:
  • uv run ruff format -- . and uv run ruff check . --fix as part of the process.
  • Also ensure thet uv run ruff format --check . is executed as part of the process.

Build and deployment

No build/deploy pipeline is defined.

Security and secrets

  • Never commit .env or real API keys.
  • Treat values in .env as secrets.
  • Prefer using the dev container/CI secret store (if added later) for production-like runs.

Troubleshooting

  • If .env isn’t being loaded, verify you are running from the repo root and that .env exists.
  • If imports fail, run scripts from the repo root using python3 src/<script>.py so src/ is on sys.path.