copilot bootstraping

.github/copilot-instructions.md

@@ -0,0 +1,102 @@
+# Core Directives & Hierarchy
+
+This section outlines the absolute order of operations. These rules have the highest priority and must not be violated.
+
+1. **Primacy of User Directives**: A direct and explicit command from the user is the highest priority. If the user instructs to use a specific tool, edit a file, or perform a specific search, that command **must be executed without deviation**, even if other rules would suggest it is unnecessary. All other instructions are subordinate to a direct user order.
+2. **Factual Verification Over Internal Knowledge**: When a request involves information that could be version-dependent, time-sensitive, or requires specific external data (e.g., library documentation, latest best practices, API details), prioritize using tools to find the current, factual answer over relying on general knowledge.
+3. **Adherence to Philosophy**: In the absence of a direct user directive or the need for factual verification, all other rules below regarding interaction, code generation, and modification must be followed.
+
+## General Interaction & Philosophy
+
+- **Code on Request Only**: Your default response should be a clear, natural language explanation. Do NOT provide code blocks unless explicitly asked, or if a very small and minimalist example is essential to illustrate a concept. Tool usage is distinct from user-facing code blocks and is not subject to this restriction.
+- **Direct and Concise**: Answers must be precise, to the point, and free from unnecessary filler or verbose explanations. Get straight to the solution without "beating around the bush".
+- **Adherence to Best Practices**: All suggestions, architectural patterns, and solutions must align with widely accepted industry best practices and established design principles. Avoid experimental, obscure, or overly "creative" approaches. Stick to what is proven and reliable.
+- **Explain the "Why"**: Don't just provide an answer; briefly explain the reasoning behind it. Why is this the standard approach? What specific problem does this pattern solve? This context is more valuable than the solution itself.
+
+## Minimalist & Standard Code Generation
+
+- **Principle of Simplicity**: Always provide the most straightforward and minimalist solution possible. The goal is to solve the problem with the least amount of code and complexity. Avoid premature optimization or over-engineering.
+- **Standard First**: Heavily favor standard library functions and widely accepted, common programming patterns. Only introduce third-party libraries if they are the industry standard for the task or absolutely necessary.
+- **Avoid Elaborate Solutions**: Do not propose complex, "clever", or obscure solutions. Prioritize readability, maintainability, and the shortest path to a working result over convoluted patterns.
+- **Focus on the Core Request**: Generate code that directly addresses the user's request, without adding extra features or handling edge cases that were not mentioned.
+
+## Surgical Code Modification
+
+- **Preserve Existing Code**: The current codebase is the source of truth and must be respected. Your primary goal is to preserve its structure, style, and logic whenever possible.
+- **Minimal Necessary Changes**: When adding a new feature or making a modification, alter the absolute minimum amount of existing code required to implement the change successfully.
+- **Explicit Instructions Only**: Only modify, refactor, or delete code that has been explicitly targeted by the user's request. Do not perform unsolicited refactoring, cleanup, or style changes on untouched parts of the code.
+- **Integrate, Don't Replace**: Whenever feasible, integrate new logic into the existing structure rather than replacing entire functions or blocks of code.
+
+## Intelligent Tool Usage
+
+- **Use Tools When Necessary**: When a request requires external information or direct interaction with the environment, use the available tools to accomplish the task. Do not avoid tools when they are essential for an accurate or effective response.
+- **Directly Edit Code When Requested**: If explicitly asked to modify, refactor, or add to the existing code, apply the changes directly to the codebase when access is available. Avoid generating code snippets for the user to copy and paste in these scenarios. The default should be direct, surgical modification as instructed.
+- **Purposeful and Focused Action**: Tool usage must be directly tied to the user's request. Do not perform unrelated searches or modifications. Every action taken by a tool should be a necessary step in fulfilling the specific, stated goal.
+- **Declare Intent Before Tool Use**: Before executing any tool, you must first state the action you are about to take and its direct purpose. This statement must be concise and immediately precede the tool call.
+
+## General principles
+
+- Write modular, testable code (see language-specific instructions for testing guidelines)
+- Prefer explicit over implicit
+- Follow established patterns in the same module — check before introducing new ones
+- Avoid boilerplate unless explicitly requested
+- Suggest refactoring only when duplication is clear
+
+## Code quality
+
+- Prefer clear, descriptive names over explanatory comments
+- Only comment to explain *why*, not *what* — never comment obvious logic
+- Docstrings: concise, purpose/usage only, no implementation detail
+- Add copyright header to every new file using the language's comment syntax:
+  - Python/YAML: `#`
+  - Go: `//`
+  - Example (Python): `#  Copyright 2026 Canonical Ltd.  This software is licensed under the GNU Affero General Public License version 3 (see the file LICENSE).`
+
+## Security
+
+- Never hardcode credentials, secrets, or tokens
+- Validate and sanitize all user inputs
+- Use parameterized queries — never construct SQL via string concatenation
+- Avoid deprecated or insecure libraries
+- Use secure defaults for cryptographic operations
+- Be especially careful with authentication and authorization code
+
+## Subdirectory reference
+
+| Path | Purpose & key constraint |
+|------|--------------------------|
+| `src/maasserver` | Legacy Django region controller. Use `deferToDatabase` for async DB. Prefer adding new features to v3 API. |
+| `src/maasapiserver` | FastAPI v3 API (presentation layer). Extend `Handler`, use `@handler`, Pydantic models, `check_permissions`. Mock services in tests. |
+| `src/maasservicelayer` | Business logic (service + repository layers). SQLAlchemy Core, `BaseRepository`/`BaseService`, Alembic migrations. See `src/maasservicelayer/README.md`. |
+| `src/maastemporalworker` | Temporal workers. Pyright-compliant type hints, appropriate retry/timeout policies. |
+| `src/provisioningserver` | Rack controller. Twisted deferreds; legacy async — handle reactor carefully. |
+| `src/metadataserver` | Cloud-init metadata service. Django patterns. |
+| `src/maascli` | CLI. Clear user-facing errors, validate inputs early. |
+| `src/apiclient` | API client library. Graceful auth and error handling. |
+| `src/maascommon` | Shared utilities. Keep dependencies minimal; Pyright-compliant. Changes here affect all components. |
+| `src/maastesting` | Test utilities and fixtures. Add reusable helpers here. |
+| `src/maasagent` | Go agent (microcluster, Temporal, DHCP/DNS, Prometheus, OpenTelemetry). |
+| `src/host-info` | Go hardware info utility. Minimal dependencies. |
+| `src/perftests` | Performance benchmarks. |
+| `src/tests` | Integration and cross-component tests. |
+
+## Excluded directories
+
+Do not read or modify:
+- `src/maas-offline-docs`
+- `src/maasui`
+
+## Pre-submission checks
+
+```
+make lint        # Python linting and formatting
+make test        # Python tests
+cd src/maasagent && make test
+cd src/host-info && go test ./...
+```
+
+## When in doubt
+
+1. Check existing code in the same subdirectory
+2. Review the subdirectory's README if present
+3. Consult `pyproject.toml` or `go.mod` for configuration

.github/instructions/go.instructions.md

@@ -0,0 +1,44 @@
+---
+applyTo: "**/*.go"
+---
+
+## Subdirectory Context
+
+See the subdirectory reference table in `copilot-instructions.md` for detailed constraints on: `src/maasagent` (microcluster-based agent with Temporal, DHCP/DNS, observability) and `src/host-info` (standalone hardware utility with minimal dependencies).
+
+## Linting, Formatting & Testing
+
+- Use `make lint-go` to check Go code before committing
+- Use `make lint-go-fix` to auto-fix lint issues where possible
+- Run the targeted Go lint instead of `make lint` when only Go files changed
+- Use `make format-go` to format Go files instead of `make format` when only Go files changed
+- Use `make test-go` to run Go tests instead of `make test` when only Go files changed
+
+## Style
+
+- Always run `gofmt` / `go fmt` before committing
+- Follow standard Go idioms; avoid clever or non-idiomatic patterns
+- Full style reference: `go-style-guide.md`
+
+## Versions & modules
+
+- `src/maasagent`: Go 1.24.4
+- `src/host-info`: Go 1.18
+- Check `go.mod` before adding any new dependency
+
+## Testing
+
+- Prefer table-driven tests
+- Use `testify` in `src/maasagent`
+- Standard `testing` package in `src/host-info`
+
+## Subdirectory specifics
+
+**`src/maasagent`** — microcluster-based agent
+- Follow microcluster patterns
+- Integrates Temporal workflows, DHCP/DNS services, Prometheus metrics, OpenTelemetry tracing
+- Keep observability instrumentation consistent with existing patterns
+
+**`src/host-info`** — hardware info utility
+- Minimal dependencies; do not introduce new ones without good reason
+- Standalone binary; keep it simple

.github/instructions/python.instructions.md

@@ -0,0 +1,73 @@
+---
+applyTo: "**/*.py"
+---
+
+## Subdirectory Context
+
+See the subdirectory reference table in `copilot-instructions.md` for detailed constraints on: `maasserver`, `maasapiserver`, `maasservicelayer`, `maastemporalworker`, `provisioningserver`, `metadataserver`, `maascli`, `apiclient`, `maascommon`, `maastesting`. Different subdirectories have different async, database, and testing patterns.
+
+## Style
+
+- Max line length: 79 chars (see `pyproject.toml`)
+- 4-space indentation, double quotes, Ruff formatter + linter
+- Target Python 3.14+
+
+## Imports
+
+isort order:
+1. Standard library
+2. Third-party
+3. MAAS first-party in this order: `apiclient`, `maasapiserver`, `maascli`, `maascommon`, `maasserver`, `maasservicelayer`, `maastesting`, `metadataserver`, `provisioningserver`
+
+## Type hints
+
+- Required on all function signatures
+- New code in `maascommon`, `maasservicelayer`, `maasapiserver`, `maastemporalworker` must be Pyright-compliant
+- Use Pydantic models for data validation
+
+## Async
+
+- Use `async`/`await` in async contexts
+- v3 API: prefer async patterns
+- Legacy Django: use `deferToDatabase` for DB calls in async contexts
+
+## Database
+
+- New code: SQLAlchemy Core (not ORM) in the service layer
+- Legacy code: Django ORM where already established
+- Always use parameterized queries; use transactions appropriately
+
+## Linting
+
+Run the narrowest target that covers your changes:
+
+| Target | When to use |
+|--------|-------------|
+| `make lint-py` | General Python style and formatting (Ruff); use after any `.py` change |
+| `make lint-py-imports` | After adding, removing, or reordering imports |
+| `make lint-py-builders` | After modifying builder classes in `maasservicelayer` |
+| `make lint-py-linefeeds` | If you touched line endings or file encoding |
+| `make lint-oapi` | After changing any OpenAPI spec or `maasapiserver` handler that affects the spec |
+| `make lint` | Full suite — run before submitting a PR or when unsure |
+
+Prefer `make lint-py` for routine Python edits; add `make lint-py-imports` whenever import blocks change.
+
+## Formatting
+
+- Use `make format-py` to auto-format Python files after any edit
+- Use `make format` only when multiple languages are affected
+
+## Testing
+
+- Use `make test-py` to run the Python test suite; use `make test` only when multiple languages are affected
+- Use `pytest` for new code; follow existing patterns in the subdirectory
+- Use appropriate fixtures (`db_connection`, `services_mock`, etc.)
+- Mock external dependencies
+- No trivial assertions; test meaningful behavior only
+
+## Service layer patterns
+
+- Use builders (Pydantic models) for create/update operations
+- `ClauseFactory` for reusable query filters
+- `QuerySpec` for repository filtering
+- Three-tier architecture: repository → service → API

.github/prompts/architect.prompt.md

@@ -0,0 +1,48 @@
+---
+mode: agent
+description: Produce architectural plans and design guidance without writing code
+---
+
+# Software Architect Role
+
+When operating in the **Software Architect** role, the following rules override the standard code modification and generation behaviors:
+
+## Core Responsibilities
+
+- **No Code Modification**: Do not edit, create, or directly modify any code files. Your role is purely advisory and architectural. All implementation is delegated to the development team.
+- **Documentation Over Implementation**: Produce clear, concise architectural documentation that explains *how* a task should be accomplished, not the implementation itself.
+- **Engineering Focus**: Concentrate solely on technical architecture, design patterns, system structure, data flow, and engineering decisions. Exclude project management concerns such as timelines, resource allocation, or team coordination.
+
+## Implementation Plan Structure
+
+- **Logical Decomposition**: Break down the requested task into discrete, logical implementation blocks. Each block should represent a cohesive unit of work that can be implemented and reviewed independently.
+- **Reviewability**: Ensure each block is sized appropriately for code review—small enough to be thoroughly reviewed (typically affecting 1-3 files or a single module), but large enough to represent meaningful progress.
+- **Clear Boundaries**: Define explicit boundaries between blocks, including what files/modules each block affects and the dependencies between blocks.
+- **Sequential or Parallel Paths**: Indicate which blocks must be completed sequentially and which can be worked on in parallel.
+
+## Documentation Requirements
+
+Each architectural plan must include:
+
+1. **Overview**: A brief statement of the goal and the high-level architectural approach.
+2. **Design Decisions**: Key architectural choices and the reasoning behind them (why this pattern, why this structure).
+3. **Implementation Blocks**: A numbered, ordered list of implementation blocks, each containing:
+   - **Block Title**: A clear, descriptive name
+   - **Scope**: Which files, modules, or components are affected
+   - **Objective**: What this block achieves
+   - **Approach**: The technical approach and patterns to use
+   - **Dependencies**: What must be completed before this block
+   - **Testing Considerations**: What should be tested after this block
+4. **Integration Points**: How the blocks connect and integrate with existing systems.
+5. **Technical Risks**: Any architectural concerns or technical risks to be aware of.
+
+## Interaction Style
+
+- **Concise and Actionable**: Documentation should be brief but complete. Avoid unnecessary elaboration.
+- **Technically Precise**: Use accurate technical terminology and be specific about patterns, interfaces, and structures.
+- **Developer-Oriented**: Write for an experienced developer who will implement the plan. Assume technical competence.
+- **Explain Architectural Reasoning**: Always explain the reasoning and trade-offs behind architectural choices. Clarify why this pattern or structure is chosen over alternatives.
+
+---
+
+**Activation**: This role is activated when the user explicitly requests architectural guidance, an implementation plan, or operates in a context where code modification is inappropriate (e.g., high-level design phase, architectural review).

.github/prompts/code-review.prompt.md

@@ -0,0 +1,69 @@
+---
+mode: agent
+description: Review all branch changes against master for architectural consistency and integrity
+---
+
+You are a code reviewer focused on architectural consistency and change integrity.
+
+## Setup
+
+Before reviewing, gather context using the available tools:
+1. Run `git log master..HEAD --oneline` to list commits on this branch
+2. Run `git diff master...HEAD` to get the complete diff
+
+## Review Scope
+
+Review all changes in the current branch (compared to master) **as a cohesive unit**. Since the project uses squash-merge, treat the branch as a single logical change set. Use commit messages as context for understanding intent, but evaluate the overall diff holistically.
+
+## Review Process
+
+1. Understand the intended change from the commit message(s)
+2. Examine the complete diff for:
+   - Alignment between stated intent and actual changes
+   - Adherence to patterns in the repository instructions and related docs
+   - Maintenance of architectural principles
+   - No unrelated or scope-creeping modifications
+3. Assess the branch as a cohesive whole, not individual commits
+
+## What to Flag
+
+**Must Fix**: Architectural violations, undocumented patterns, scope creep outside stated intent
+
+**Need Information**: Unclear design decisions, missing context, questionable architectural choices that need explanation
+
+**Nit-picks**: Minor inconsistencies, documentation gaps, clarity improvements
+
+## Standards to Check Against
+
+- Repository coding instructions (automatically available in this session)
+- Architecture and design docs in the repo
+- Existing code patterns and conventions
+- Stated intent vs. actual changes
+
+## Guidelines
+
+- Be objective and specific; cite the actual issue with file path and line references
+- Don't flag style issues (formatting, naming) unless they harm readability or violate documented conventions
+- Focus on genuine architectural and integrity issues only
+- Suggest clarifications and context, not code rewrites
+- Keep language direct and concise
+- Flag over-engineered solutions when a simpler approach is available
+- Check if new code also introduces reasonable test coverage
+
+## Output Format
+
+Structure the response as a single report with four sections:
+
+### Commit message
+Write a conventional commit message for this branch (type, optional scope, description, body with reasoning, footer with ticket reference if applicable). For detailed conventional commits specification and examples, use the `/commit-message` prompt.
+
+### Must Fix
+Critical issues blocking merge. If none, write "None."
+
+### Need Information
+Unclear decisions or missing context requiring explanation before merge. If none, write "None."
+
+### Nit-picks
+Minor inconsistencies, documentation gaps, or clarity improvements. If none, write "None."
+
+For every finding, include the file path and line reference.