# Contributing to agentic-devtools

Thank you for your interest in contributing to agentic-devtools! This guide will help you get started with development, testing, and submitting changes.

## Getting Started

### Prerequisites

- Python 3.8 or higher
- Git
- pip or pipx

### Clone the Repository

```bash
git clone https://github.com/ayaiayorg/agentic-devtools.git
cd agentic-devtools
```

### Development Environment Setup

#### Option 1: Dev Container (Recommended)

This repository includes a dev container configuration for Python development. This is the easiest way to get started:

- **VS Code**: Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), then click "Reopen in Container"
- **GitHub Codespaces**: Create a new Codespace - all dependencies will be set up automatically

See [.devcontainer/README.md](.devcontainer/README.md) for more details.

#### Option 2: Local Development

Install the package in editable mode with development dependencies:

```bash
pip install -e ".[dev]"
```

This installs agentic-devtools with all development tools including pytest, black, isort, mypy, and ruff.

## Running Tests

### Test Organization Policy

New unit tests must follow the **1:1:1 policy**: one test file per symbol (function or class), in a directory
that mirrors the source structure. See [tests/README.md](tests/README.md) for the full policy,
rationale, and how to add new tests.

**Quick path convention:**

```text
tests/unit/{module_path}/{source_file_name}/test_{symbol_name}.py
```

Run the structure validator before pushing:

```bash
python scripts/validate_test_structure.py
```

### Full Test Suite

Run the complete test suite with coverage:

```bash
pytest --cov=agentic_devtools --cov-report=term-missing
```

**⚠️ AI agents working on AGDT MUST use `agdt-test` commands — NEVER run pytest directly:**

```bash
# Run full test suite with coverage (background task)
agdt-test
agdt-task-wait

# Run tests quickly without coverage
agdt-test-quick
agdt-task-wait

# Run specific test file or pattern (synchronous)
agdt-test-pattern tests/test_jira_helpers.py
agdt-test-pattern tests/test_jira_helpers.py::TestClassName::test_method
```

Running `pytest` directly bypasses the background task system and workflow integration.
See `.github/copilot-instructions.md` for the full command mapping policy and rationale.

### E2E Smoke Tests

End-to-end smoke tests verify the complete workflow including Azure DevOps and Jira integration. These tests are located in the `tests/` directory and typically require environment variables to be set:

- `AZURE_DEV_OPS_COPILOT_PAT` - Azure DevOps Personal Access Token
- `JIRA_COPILOT_PAT` - Jira API token
- `JIRA_BASE_URL` - Jira instance URL

Run E2E tests with:

```bash
pytest tests/test_e2e_*.py -v
```

## TDD Workflow

This project requires **Test-Driven Development (TDD)** for all implementation work.
Write tests **before** implementation code. The red-green-refactor cycle is mandatory.

### Red-Green-Refactor Cycle

1. **RED** — Write a failing test that defines the expected behaviour. Run it to confirm it fails.
2. **GREEN** — Write the minimal implementation to make the test pass. Run it to confirm it passes.
3. **REFACTOR** — Improve code structure and clarity while keeping tests green.

### TDD Example

```bash
# 1. Write the test first (no source changes yet)
# Create tests/unit/cli/git/core/test_new_function.py

# 2. Confirm the test fails (RED)
agdt-test-pattern tests/unit/cli/git/core/test_new_function.py -v
# Expected: FAILED

# 3. Write minimal implementation
# Edit agentic_devtools/cli/git/core.py

# 4. Confirm tests pass (GREEN)
agdt-test-pattern tests/unit/cli/git/core/test_new_function.py -v
# Expected: PASSED

# 5. Refactor and re-run focused tests (REFACTOR)
# NOTE: use agdt-test-pattern, NOT agdt-test-file — agdt-test-file only supports
# legacy flat test files (tests/test_<module>.py) and will fail for 1:1:1 tests
agdt-test-pattern tests/unit/cli/git/core/ -v

# 6. Run the full suite when all work is complete
agdt-test
agdt-task-wait
```

### Rules

- Never write source code before a failing test exists.
- Never skip the RED step — a test that passes without any implementation is not testing anything.
- Keep each RED → GREEN cycle small: one function or behaviour at a time.
- All new code must maintain 100% test coverage (enforced by CI).

## Code Quality

We maintain high code quality standards using multiple tools. All code must pass these checks before being merged.

### Formatting

**Black**: Code formatting

```bash
black agentic_devtools tests
```

**isort**: Import sorting

```bash
isort agentic_devtools tests
```

### Type Checking

**mypy**: Static type checking

```bash
mypy agentic_devtools
```

### Linting

**ruff**: Fast Python linter

```bash
ruff check agentic_devtools tests
```

**markdownlint**: Markdown linting

```bash
markdownlint-cli2 "**/*.md"
```

### Running All Quality Checks

Run all quality checks at once:

```bash
# Format code
black agentic_devtools tests
isort agentic_devtools tests

# Check types
mypy agentic_devtools

# Lint code
ruff check agentic_devtools tests

# Lint markdown
markdownlint-cli2 "**/*.md"
```

## Using agdt Commands vs Raw Commands

AI agents working on `agentic-devtools` **must** prefer `agdt-*` CLI commands over raw equivalents.
Using raw commands bypasses the background task system, workflow integration, auto-approval benefits,
and dry-run safety.

### Command Mapping

| Instead of... | Use... |
|---------------|--------|
| `git add . && git commit && git push` | `agdt-git-save-work` |
| `git commit --amend` | `agdt-git-save-work` (auto-detects amend) |
| `git push --force` | `agdt-git-force-push` |
| `git push -u origin <branch>` | `agdt-git-publish` |
| `pytest ...` | `agdt-test`, `agdt-test-file`, `agdt-test-pattern`, `agdt-test-quick` |
| Raw Azure DevOps REST API calls | `agdt-create-pull-request`, `agdt-add-pull-request-comment`, etc. |
| Raw Jira REST API calls | `agdt-add-jira-comment`, `agdt-get-jira-issue`, etc. |
| `gh issue create` (for this repo) | `agdt-create-agdt-feature-issue`, `agdt-create-agdt-bug-issue`, etc. |

### Exceptions — Raw Commands Still Required

> ⚠️ No agdt equivalent yet. Switch to agdt command when support is added.

- `gh issue` / `gh pr` for repositories other than `agentic-devtools` — no agdt support yet
- `gh pr review`, `gh pr comment` for external repos — no agdt support yet
- Other `gh` operations not listed in the mapping above

See `.github/copilot-instructions.md` for the full policy and background on why this matters.

## Spec-Driven Development

This project follows the Spec-Driven Development (SDD) methodology. Before implementing new features:

1. Create a feature specification in `specs/NNN-feature-name/spec.md`
2. Develop an implementation plan in `specs/NNN-feature-name/plan.md`
3. Break down the work into tasks in `specs/NNN-feature-name/tasks.md`
4. Implement following the plan

For complete details on the SDD workflow, see [SPEC_DRIVEN_DEVELOPMENT.md](SPEC_DRIVEN_DEVELOPMENT.md).

### SDD Helper Commands

AI assistants can use these commands:

- `/speckit.agdt:specify` - Create feature specifications
- `/speckit.agdt:plan` - Develop implementation plans
- `/speckit.agdt:tasks` - Generate task lists
- `/speckit.agdt:implement` - Execute implementation
- `/speckit.agdt:analyze` - Validate cross-artifact consistency

## Protected / Auto-Generated Files

> **⚠️ IMPORTANT — AI AGENTS AND CONTRIBUTORS: Do NOT manually edit or commit these files.**

### `agentic_devtools/_version.py`

This file is **automatically generated** by `hatch-vcs` / `setuptools-scm` from Git tags at build
time. Its header says: _"file generated by setuptools-scm — don't change, don't track in version
control"_.

- The file is listed in `.gitignore` and is **not tracked by git**.
- Do **not** create, edit, or `git add` this file during development.
- Version numbers are derived from Git tags — to bump the version, create a new Git tag
  (see [RELEASING.md](RELEASING.md)).

Because the file is untracked, `.gitignore` prevents `git add .` from ever staging it — no
additional configuration is needed for either agent or developer workflows.

## Submitting Changes

### Branch Naming

Use descriptive branch names with the following patterns:

- `feature/ISSUE-KEY/description` - For new features
- `fix/ISSUE-KEY/description` - For bug fixes
- `docs/description` - For documentation changes
- `refactor/description` - For refactoring

Example: `feature/PROJECT-1234/add-webhook-support`

### Single-Commit Policy

> **⚠️ HARD RULE — AI AGENTS AND CONTRIBUTORS: Every pull request MUST contain exactly one commit.**

- **NEVER create additional commits** on a feature branch — always amend and force-push
- **NEVER use `git commit` directly** — always use `agdt-git-save-work`, which automatically
  amends when the branch has commits ahead of `main` (`origin/main` if available). This enforces
  the single-commit policy: once you have one commit on the branch, all subsequent saves amend it.
- Adding a second commit to a PR branch is a **policy violation**
- Commit messages must follow the convention described in [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md)

When making updates to a PR, `agdt-git-save-work` auto-detects that an amend is needed and
force-pushes. No manual `git commit --amend` or `git push --force` is required.

The format requires a **mandatory** GitHub issue link as the scope and repeats it in the footer:

```text
feat([#42](https://github.com/ayaiayorg/agentic-devtools/issues/42)): add webhook support

- Implemented webhook handler
- Added tests

[#42](https://github.com/ayaiayorg/agentic-devtools/issues/42)
```

See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for the full specification including
parent/child issues, multiple issues, ordering rules, and supported types.

### Pull Request Process

1. **Create a feature branch** following the naming convention
2. **Make your changes** following the code quality standards
3. **Write tests** to cover your changes
4. **Run all quality checks** (formatting, linting, type checking, tests)
5. **Commit your changes** with a descriptive message
6. **Push your branch** and create a pull request
7. **Address review feedback** by amending your commit
8. **Wait for CI checks** to pass before requesting final review

### Code Review

All PRs require code review before merging. Reviews check for:

- Code quality and adherence to standards
- Test coverage (aim for >90%)
- Documentation updates
- Compliance with SDD principles (if applicable)
- Security considerations

## Reporting Issues

### Bug Reports

When reporting bugs, please include:

- **Description**: Clear description of the issue
- **Steps to Reproduce**: Detailed steps to reproduce the problem
- **Expected Behavior**: What you expected to happen
- **Actual Behavior**: What actually happened
- **Environment**: Python version, OS, relevant package versions
- **Logs**: Any error messages or stack traces

### Feature Requests

For feature requests, please provide:

- **Use Case**: Why is this feature needed?
- **Proposed Solution**: How should it work?
- **Alternatives**: Have you considered other approaches?
- **Additional Context**: Any other relevant information

### Security Issues

For security vulnerabilities, please follow responsible disclosure:

1. **Do not** open a public issue
2. Email the maintainers directly with details
3. Allow time for the issue to be addressed before public disclosure

## Development Tips

### Using State Management

The package uses a JSON state file (`.agdt/workflows/{identity}/{worktree_key}/state.json`) for parameter passing:

```bash
# Set values
agdt-set pr_id 23046
agdt-set content "Your message"

# Get values
agdt-get pr_id
```

### Background Tasks

Many commands run as background tasks. Monitor them with:

```bash
agdt-tasks              # List all tasks
agdt-task-status        # Check specific task status
agdt-task-log           # View task logs
agdt-task-wait          # Wait for task completion
```

### Debugging

Enable dry-run mode to preview operations without executing:

```bash
agdt-set dry_run true
agdt-git-save-work  # Previews commands without executing
```

## Using the SpecKit Issue Trigger

The repository includes a GitHub Actions workflow that automatically kicks off the
Specification-Driven Development (SDD) process when a label is applied to a GitHub issue.

### How It Works

1. Create a GitHub issue describing the feature you want to build
2. Apply the `speckit` label (or your configured `SPECKIT_TRIGGER_LABEL`) to the issue
3. The `speckit-issue-trigger` workflow fires automatically:
   - Posts a "Phase 1 Started" comment within ~30 seconds
   - Generates `spec.md` via the Copilot SDK (model set by `SPECKIT_COPILOT_MODEL`)
   - Creates a branch (`speckit/<issue>/phase-1-specify`) and commits the spec
   - Opens a Pull Request labeled `speckit:phase-1`
4. Review and merge the Phase 1 PR → Phase 2 (clarify) is triggered automatically
5. Each subsequent phase creates its own PR for independent review:
   - **Phase 1**: specify → `spec.md`
   - **Phase 2**: clarify + checklist → updated `spec.md`, `checklists/requirements.md`
   - **Phase 3**: plan → `plan.md` (+ optional `research.md`, `data-model.md`, etc.)
   - **Phase 4**: tasks → `tasks.md`
   - **Phase 5**: analyze → `analysis-report.md`
6. After Phase 5 merges, `speckit:completed` and `speckit:needs-implementation` labels are applied

### Manual Trigger

You can also run the workflow manually from the **Actions** tab:

```bash
gh workflow run speckit-issue-trigger.yml \
  -f issue_number=42 \
  -f trigger_label=speckit
```

### Repository Variables

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `SPECKIT_TRIGGER_LABEL` | `speckit` | Label that triggers the SDD workflow |
| `SPECKIT_COPILOT_MODEL` | `claude-opus-4.6` | Model for Copilot SDK spec generation |
| `SPECKIT_COMMENT_ON_ISSUE` | `true` | Set to `false` to suppress issue comments |
| `SPECKIT_CREATE_BRANCH` | `true` | Set to `false` to skip branch creation |
| `SPECKIT_CREATE_PR` | `true` | Set to `false` to skip PR creation |
| `SPECKIT_AUTO_MERGE_PHASES` | _(empty)_ | Comma-separated phase names to auto-merge (e.g., `analyze`) |

### Required Secrets

| Secret | Description |
| ------ | ----------- |
| `COPILOT_APP_ID` | App ID of the `agentic-devtools-copilot-reviewer` GitHub App |
| `COPILOT_APP_PRIVATE_KEY` | PEM private key for the `agentic-devtools-copilot-reviewer` GitHub App. Required permissions: `Pull requests: Read & Write`, `Contents: Read`, `Copilot: Read` |

### Issue Labels Used

| Label | Meaning |
| ----- | ------- |
| `speckit` | Add to trigger specification generation |
| `speckit:processing` | Applied automatically during generation |
| `speckit:phase-N` | Applied to each phase PR (N = 1–5) |
| `speckit:phase-N-complete` | Applied to issue when phase N's PR merges |
| `speckit:completed` | Applied when all 5 phases are complete |
| `speckit:needs-implementation` | Applied after Phase 5 merge to trigger implementation |
| `speckit:failed` | Applied if generation fails |

### Testing the Workflow

Use the `.github/ISSUE_TEMPLATE/speckit-test.md` issue template to create a test issue
and validate the full workflow end-to-end.

## Additional Resources

- [README.md](README.md) - End-user documentation
- [SPEC_DRIVEN_DEVELOPMENT.md](SPEC_DRIVEN_DEVELOPMENT.md) - SDD workflow guide
- [RELEASING.md](RELEASING.md) - Release process documentation
- [.devcontainer/README.md](.devcontainer/README.md) - Dev container setup

## Questions?

If you have questions or need help:

- Open a discussion in the GitHub repository
- Check existing issues for similar questions
- Reach out to the maintainers

Thank you for contributing to agentic-devtools! 🎉
