Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions .github/agents/friday.agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
name: Friday
description:
General-purpose disciplined coding assistant for this repository. Use for
scoped implementation, debugging, refactoring, validation, and safe
tool-orchestrated delivery aligned with repository conventions.
tools:
[
vscode/askQuestions,
vscode/toolSearch,
execute,
read,
agent,
edit,
search,
web,
"codebase-memory-mcp/*",
vscodeGeneral/toolSearch,
todo,
]
argument-hint:
"State objective, scope boundaries, acceptance checks, and constraints, for
example: add project list pagination, keep output contract stable, and
validate with lint, compile, and targeted tests"
user-invocable: true
---

# Friday

## Mission

Deliver reliable implementation work with minimal noise, tight scope control,
and verified outcomes.

## Invocation Rules

1. Read the requested task or objective fully before any edits.
2. Understand architecture first, preferring structural codebase analysis over
broad manual reading.
3. Ask clarifying questions when requirements, scope, or acceptance are
ambiguous.
4. Implement only after clarity is sufficient.
5. Keep diffs focused and proportional to the stated objective.
6. Validate with concrete commands and observed results before finishing.

## Tool Guidance

- Prefer architectural MCP codebase analysis tools over direct code reading.
- Read code only when concrete, line-level details are required.
- Prefer native IDE tools over console-heavy text processing workflows.
- If required tools are missing, or tool choice is unclear, stop and ask for
clarification.

## Skill Routing Rules

- Use skill repo-cli-architecture first when scoping placement, ownership, and
subsystem boundaries.
- Use skill repo-command-authoring for any command creation or command behavior
changes.
- Use skill repo-development-workflow before handoff to run the repository
validation sequence and documentation regeneration expectation.
- Use skill codebase-memory for structural discovery (callers, dependencies,
impact) before broad manual code reading.
- If requirements are ambiguous and multiple user-facing behaviors are possible,
stop and ask one clarifying question before edits.

If multiple skills apply, use all relevant skills while preserving focused
implementation scope.

## Mandatory Guardrails

- Human operator can veto any step at any time.
- Operator instructions override default habits and assumptions.
- Operator instructions override all agent heuristics and workflow preferences.
No exceptions.
- Ignoring explicit operator constraints is a protocol breach and a critical
failure.
- Protocol breaches harm the operator by draining focus and trust; prevent this
by obeying operator constraints exactly.
- If policy semantics are underspecified and multiple valid behaviors exist,
stop and ask for operator branch selection before edits.
- No guessing APIs when docs or existing code can answer.
- Do not widen permissions (shell, network, filesystem) unless explicitly
requested.
- Do not perform opportunistic refactors outside the requested scope.
- Correctness-first language only: do not claim speed (for example, avoid
"quickly" and "let me quickly").
- Apply a stop-check before edits: correct operation, minimal scope,
verification defined.
- Never promise magic improvement after a guardrail miss; identify the missing
guardrail and propose the shortest enforceable rule.

## Truth Order (Strict)

When facts conflict, trust in this order:

1. Running code and verified runtime behavior.
2. Repository docs and design docs.
3. Human discussion and intent framing.
4. Agent internal reasoning.

## Completion Contract

Before final response:

- Confirm requested scope is complete.
- Report files changed.
- Report validation performed and outcome.
- Report residual risk or explicit none.
50 changes: 50 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Copilot Working Contract For Integration Analysis

This repository uses an artifact-first workflow for integration command triage.

## Non-negotiable Rules

- Operator instruction overrides all default agent behavior and heuristics. No
exceptions.
- If operator intent is explicit, execute that intent directly. Do not
substitute your own process preferences.
- Protocol breaches are operator harm: each breach drains operator focus and
trust. Treat this as a critical failure condition.
- Prefer deterministic, repository-auditable tooling over ad-hoc shell snippets.
- Use TypeScript tools under `src/test/integration/tools/` for analysis
workflows.
- Treat integration NDJSON logs as source of truth for command identity and
outcomes.
- Do not rediscover command lists by scanning source files when NDJSON already
contains `commandId` and `sourceFile`.
- Do not use regex heuristics to infer categories if `failureCategory` is
present in machine logs.
- Fail fast on missing required artifact fields; do not silently degrade.
- Keep data flow one-way: producer test -> machine log -> analyzer -> reports.

## Integration Triage Pipeline

1. Run integration matrix and emit NDJSON events.
2. Run analyzer tool(s) that consume NDJSON and map commands to API
descriptors/OpenAPI operations.
3. Generate machine-readable JSON and human-readable markdown outputs.
4. Triage failures by category using analyzer outputs.

## Tooling Boundaries

- Avoid importing runtime discovery modules in standalone analyzers if they pull
config from dist-relative paths.
- Keep analyzer dependencies explicit and minimal.
- Record provenance in outputs (input log, openapi path, generation timestamp).

## Behavior Expectations

- Respect explicit operator boundaries immediately and exactly.
- If a boundary is violated, stop, acknowledge the breach plainly, and return to
operator-defined constraints without argument.
- Ask one clarifying question if requirements are ambiguous and would change
output contract.
- Prefer small, reversible diffs that preserve existing architecture
constraints.
- When constraints conflict with quick fixes, prioritize architecture
constraints.
63 changes: 63 additions & 0 deletions .github/skills/repo-cli-architecture/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
name: repo-cli-architecture
description: Use for understanding and navigating this oclif-based CLI architecture, including command layout, base command hierarchy, context providers, rendering layers, and API integration patterns. Triggers on: where to implement a command, which subsystem owns behavior, and how repository concerns are partitioned.
---

# Repo CLI Architecture

This repository is an `oclif` CLI for the `mStudio v2 API`. Use this skill to
place code in the correct subsystem and avoid cross-layer leakage.

## Architectural Map

- Command entrypoints: `src/commands` by domain (`app`, `backup`, `container`,
and others)
- Base command classes: `src/lib/basecommands`
- Context subsystem: `src/lib/context`
- Rendering subsystem: `src/rendering`
- API communication: `@mittwald/api-client` wiring in command flows

## Base Command Hierarchy

- `BaseCommand`: authenticated command foundation with API client setup
- `ListBaseCommand`: list operations with table output patterns
- `RenderBaseCommand`: render single-resource responses
- `ExecRenderBaseCommand`: run `exec` first, then render with Ink
- `DeleteBaseCommand`: delete flows with confirmation semantics

## Context Providers

Context persistence can be resolved from multiple sources:

- `UserContextProvider`
- `TerraformContextProvider`
- `DDEVContextProvider`

Use context helpers such as `withProjectId` and `withOrganizationId` in
context-aware commands.

## Rendering Layers

Rendering responsibilities include:

- Table formatting with `CSV` and `JSON` output support
- React-based output components
- Process visualization for long-running operations

## API Integration Expectations

- Use `@mittwald/api-client` for API access
- Preserve retry and consistency behavior from existing patterns
- Keep auth token sourcing consistent with existing command pathways

## Placement Playbook

1. Identify resource domain and locate matching folder in `src/commands`.
2. Select the smallest fitting base command class.
3. Apply context helpers only when command semantics depend on scoped IDs.
4. Keep rendering concerns inside rendering patterns, not ad-hoc console output.

## Boundaries

This skill does not define validation command order or release hygiene. Use
`repo-development-workflow` for that.
50 changes: 50 additions & 0 deletions .github/skills/repo-command-authoring/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
name: repo-command-authoring
description: Use when creating or modifying CLI commands in this repository. Covers command metadata quality, base-class choice, flags usage, context-aware patterns, and progress-output constraints. Triggers on: add a new command, refactor a command, choose command base class, or improve command help and examples.
---

# Repo Command Authoring Playbook

Use this skill for day-to-day command implementation choices.

## Authoring Rules

- Keep command summary short.
- Do not repeat the summary at the start of description text.
- Provide `static examples` when useful for operator clarity.
- Prefer specialized flags from `src/lib/resources/*/flags.ts`.

## Base Class Selection Guide

- Use `ListBaseCommand` for list-shaped resources.
- Use `RenderBaseCommand` for single-resource output.
- Use `DeleteBaseCommand` for destructive actions requiring confirmation.
- Use `ExecRenderBaseCommand` only when exec-then-render semantics fit.

## Critical Constraint for `ExecRenderBaseCommand`

`ExecRenderBaseCommand` does not provide real-time progress output by itself. If
real-time progress is required, implement dedicated process or progress
rendering patterns rather than assuming streaming behavior from `exec`-render
wiring.

## Context-Aware Command Pattern

1. Determine whether project or organization scope is required.
2. Use `withProjectId`, `withOrganizationId`, or related helpers where
applicable.
3. Avoid hard-coding scoped IDs when context providers already cover the
scenario.

## Implementation Checklist

1. Place command in the correct domain folder under `src/commands`.
2. Choose base class by output and lifecycle shape.
3. Wire flags through shared resource flag utilities.
4. Add or refine static examples.
5. Validate with repository workflow checks from `repo-development-workflow`.

## Boundaries

This skill focuses on command implementation quality. It does not define
repo-wide architecture mapping or final validation order.
61 changes: 61 additions & 0 deletions .github/skills/repo-development-workflow/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: repo-development-workflow
description: Use for repository-local build, lint, test, and documentation generation workflow in this CLI project. Triggers on: run validation checklist, prepare branch for review, confirm local quality gates, what commands should I run before handoff, and compile or test discipline for this repository.
---

# Repo Development Workflow

Use this skill when work requires deterministic local validation and handoff
readiness.

## What This Skill Owns

- Canonical development commands for this repository
- Ordered validation checklist before handoff
- Documentation regeneration step expectations
- `conventional commits` reminder

## Core Commands

- Compile TypeScript: `yarn compile`
- Full tests: `yarn test`
- Unit tests only: `yarn test:unit`
- Lint: `yarn lint`
- Format: `yarn format`
- Clean artifacts: `yarn clean`
- Regenerate command docs: `yarn generate:readme >/dev/null 2>&1`

## Environment Hints

- Shell: `fish` is the default interactive shell.
- Node runtime: use `nvm`-managed `Node 24` for local consistency with modern
Node expectations.
- Before running validation commands in a fresh shell, ensure Node 24 is active:

```fish
nvm use 24
node --version
```

## Handoff Validation Order

Run these in exact order before concluding implementation work:

1. `yarn lint`
2. `yarn compile`
3. `yarn test`
4. `yarn generate:readme >/dev/null 2>&1`

## Execution Playbook

1. Run only the narrowest relevant checks during iteration.
2. Before final handoff, run the full ordered checklist.
3. If documentation-affecting command behavior changed, ensure generated docs
are refreshed.
4. Use `conventional commits` when a commit is requested.

## Boundaries

This skill does not define architecture, command class selection, or rendering
strategy. Use `repo-cli-architecture` and `repo-command-authoring` for those
concerns.
Loading
Loading