<!--
Sync Impact Report
- Version change: 1.3.0 -> 1.4.0
- Added principles:
   - XV. Living Workflow Expectation Docs
- Modified principles: None
- Added sections: None
- Modified sections: None
- Removed sections: None
- Templates requiring updates: None
- Related issues:
   - #2151 (general workflow expectation templates + mermaid diagrams)
- Follow-up TODOs: None
-->

# agentic-devtools Constitution

## Core Principles

### I. Scoped Tool Availability

Each workflow step must have a precisely defined set of tools and commands available to it:

- Workflow definitions declare explicit capability sets per step
- Tools and commands are scoped to the minimum required for each operation
- Auto-approval and autopilot modes are recognized as temporary workarounds, not design goals
- Generic patterns (e.g., `agdt-set key value`) remain for flexibility but are not the primary scoping mechanism

**Rationale**: Explicit capability declarations improve safety, auditability, and predictability of AI-driven workflows.

### II. State Architecture

State management uses a dual-layer approach:

- **CLI state**: Single `state.json` per workflow directory (`.agdt/workflows/{identity}/{worktree_key}/state.json`)
- **Orchestration state**: LangGraph checkpointing for multi-step workflow recovery when running `--engine langchain`
- Transparent state inspection via `agdt-show`
- Atomic state updates with file locking
- Worktree/identity-scoped isolation with file locking for concurrent task safety

**Rationale**: Enables reliable orchestration with checkpoint recovery while maintaining CLI-level state transparency and parallel safety.

### III. Background Task Architecture

All action commands that mutate state or perform API calls must run as background tasks:

- Commands spawn async processes and return immediately with task ID
- Results written to output files when complete
- Monitoring via `agdt-task-status`, `agdt-task-log`, `agdt-task-wait`
- Prevents AI agents from timing out or thinking operations failed

**Rationale**: Enables reliable execution of long-running operations in AI-driven workflows.

### IV. Test-Driven Development & Coverage

All features must follow TDD practices:

- Tests written before implementation
- Overall package coverage must remain at 100% (`--cov-fail-under=100`); new or changed lines must be covered
- Unit tests for new logic and integration tests for all CLI commands
- Use `agdt-test` commands (never run pytest directly)
- Background task execution for test runs
- Any exception to coverage requires explicit justification in the PR

**Rationale**: Ensures reliability and maintainability of automation tools.

### V. Code Quality & Maintainability

All changes must meet explicit quality and maintainability standards:

- Public APIs MUST include type hints and docstrings
- Linting and formatting MUST pass without warnings
- Changes MUST avoid dead code and unused configuration
- Error handling MUST be explicit and actionable (no silent failures)

**Rationale**: Ensures reliable automation and long-term maintainability.

### VI. User Experience Consistency

CLI user experience must be consistent and predictable:

- Command naming, flags, and state keys MUST follow existing patterns
- Output MUST be structured, concise, and include next-step guidance
- Error messages MUST explain cause and resolution steps

**Rationale**: Enables AI and human users to operate the CLI confidently.

### VII. Performance & Responsiveness

Performance requirements must be explicit and enforced:

- Any synchronous CLI command MUST complete within 2 seconds on typical inputs
- Operations expected to exceed 2 seconds MUST use background tasks
- Network calls MUST set timeouts and include retry logic where safe
- Performance expectations MUST be documented in specs and validated in tests

**Rationale**: Prevents workflow stalls and supports reliable automation.

### VIII. Python Package Best Practices

Follow standard Python packaging conventions:

- Clear module organization under `agentic_devtools/`
- Entry points defined in `pyproject.toml`
- Type hints for all public APIs
- Comprehensive docstrings
- Cross-platform compatibility (Windows/Linux/macOS)

**Rationale**: Maintains professional standards and enables easy installation/distribution.

### IX. LangGraph Orchestration

Multi-step workflows using `--engine langchain` use LangGraph with checkpoint state recovery:

- Workflow state persisted via LangGraph checkpointing for resumability
- Human-in-the-loop interrupts at defined decision points
- Automatic retry and recovery from transient failures
- Clear separation between orchestration state and CLI state

**Rationale**: Provides reliable, resumable multi-step workflow execution with built-in recovery.

### X. Dual-Engine Compatibility

New orchestration engines must coexist with existing execution paths:

- Explicit opt-in routing via `--engine` flag
- Failures in one engine MUST NOT affect the other
- Both engines share the same CLI commands and state interfaces
- Migration between engines is user-initiated, never automatic

**Rationale**: Enables incremental adoption of new orchestration without disrupting existing workflows.

### XI. Pre-1.0 Flexibility

Until v1.0.0, the project prioritizes optimization over stability:

- Breaking changes are allowed and expected
- Optimization and simplification preferred over backward compatibility
- Dead code, unused config, and deprecated paths should be actively removed
- No migration plans or deprecation periods required pre-1.0

**Rationale**: Enables rapid iteration and architectural improvements during early development.

### XII. Structured Preparation for AI Agents

All AI agent workflows must follow a two-phase design pattern — deterministic data preparation followed by focused evaluation:

- Phase 1 (Preparation): Gather, collate, and organize all relevant context (PRs, diffs, comments, metadata, instruction files) using deterministic, automatable logic before invoking the AI agent
- Phase 2 (Evaluation): Provide the pre-gathered context as structured input so the agent focuses solely on analysis, judgment, or generation tasks
- Agents must not be required to fetch, crawl, or discover context at runtime when that context could have been prepared deterministically
- Preparation outputs must be reproducible and audit-traceable (saved to files or state keys)

**Rationale**: Reduces token consumption by 40–60%, ensures reproducibility of agent outputs, and enables audit-traceability by separating mechanical data retrieval from expensive inference.

### XIII. Provider-Agnostic Abstraction

All platform-specific integration must be handled exclusively by agentic-devtools abstractions, never by agent prompts or skill files directly:

- Agent skill files (`.agent.md`) and prompt templates (`.prompt.md`) must remain agnostic of the underlying CI, issue, or source control provider
- Provider-specific logic (GitHub, GitLab, Azure DevOps, Jira) must live in agentic-devtools CLI modules or adapter interfaces (e.g., `CIProvider`, `IssueAdapter`, `SourceControlProvider`)
- Agents interact with providers exclusively through `agdt-*` commands or the configured provider interface
- New provider onboarding requires only extending the abstraction in agentic-devtools, not modifying agent/prompt files

**Rationale**: Maximizes portability, maintainability, and test coverage. Prevents logic duplication across skills/agents and ensures new providers can be onboarded without touching agent-facing files.

### XIV. Thin Provider-Native Files

All provider-native configuration files (GitHub Actions YAML, Azure DevOps pipelines, etc.) must be minimal dispatch wrappers:

- YAML/pipeline files invoke a single `agdt-*` CLI command or entrypoint
- Business logic, orchestration, and platform/config handling live in reusable agentic-devtools code
- Provider files handle only secrets/token plumbing and basic dispatch
- Complex conditional logic in YAML is a code smell — extract it into a testable CLI command

**Rationale**: Keeps automation testable, portable, and understandable. Changing CI providers does not require rewriting brittle, vendor-locked YAML orchestration logic.

### XV. Living Workflow Expectation Docs

The general workflow expectation documents and their Mermaid diagrams under `docs/workflow-expectations/` are a source of truth for how the initiate workflows behave and MUST be kept
in sync with the code:

- Each initiate workflow has a matching `docs/workflow-expectations/<command-name>.md` document containing a Mermaid `## Workflow Diagram`
- Any change to an initiate workflow's behavior, parameters, or decision paths MUST update the corresponding document and its diagram in the **same** pull request
- These documents are general templates that auditing agents (e.g., `agdt.test-workflow`) copy and specialize per command and flags
- Reviewers MUST verify that the document and diagram match the code before approving

**Rationale**: Keeps the workflows' decision paths and side effects discoverable, reviewable, and trustworthy, and gives auditing agents an accurate baseline instead of re-deriving behavior from scratch.

## Development Workflow

### Code Changes

1. Breaking changes are permitted pre-1.0 (see Principle XI); prefer simplification over backward compatibility
2. New commands require:
   - State management pattern documentation
   - Background task integration (for actions)
   - CLI parameter support where appropriate
   - Integration tests
   - README documentation

### Testing Standards

- Use `agdt-test` for full test suite (~55 seconds, 2000+ tests)
- Use `agdt-test-quick` for rapid iteration
- Use `agdt-test-file --source-file <file>` for focused coverage (100% required)
- Use `agdt-test-pattern` for specific test selection
- All tests run as background tasks with proper log capture
- Performance expectations documented and verified for new commands

### Documentation Requirements

- README.md must document all CLI commands
- State keys must be documented with purpose and examples
- Workflow steps must include CLI usage examples
- Both explicit (CLI args) and parameterless patterns must be shown

## Quality Gates

### Pre-Commit

- All tests pass
- Overall coverage gate remains 100% (`--cov-fail-under=100`), so uncovered new/changed lines fail checks
- No linting errors
- Type checking passes
- UX output and error handling conform to established patterns

### Pre-Release

- Full test suite passes
- Documentation updated
- CHANGELOG.md updated
- Version bumped appropriately
- Performance expectations validated for new or modified commands

## Technical Constraints

### Dependencies

- Minimize external dependencies
- Only add dependencies for core functionality
- Prefer standard library when possible
- Document all dependency choices

### Platform Support

- Must work on Windows (PowerShell), Linux (bash), and macOS (zsh)
- File paths must use cross-platform utilities
- Scripts provided in both bash and PowerShell variants

### API Integration

- Azure DevOps REST API v7.1+
- Jira REST API v3
- GitHub API v3 (for future integrations)
- All API calls must include error handling and retry logic

## Governance

This constitution supersedes all other practices. All changes must comply with these principles.

### Amendments

Constitution changes require:

1. Documentation of rationale
2. Approval from maintainers
3. Version bump following semantic versioning

### Compliance

- All PRs must verify compliance with constitution
- Code reviews must reference relevant principles
- Non-compliance requires explicit justification and approval

**Version**: 1.4.0 | **Ratified**: 2026-02-02 | **Last Amended**: 2026-06-16
