@event4u/agent-config 5.10.1 → 6.0.0

package/.agent-src/skills/feature-planning/SKILL.md

@@ -1,271 +0,0 @@
----
-model_tier: inherit
-name: feature-planning
-description: "Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap."
-domain: product
-workspaces:
-  - product
-packs:
-  - product-basic
-trust:
-  level: professional
-install:
-  removable: true
----
-
-# feature-planning
-
-## When to use
-
-Use this skill when:
-- The user has a feature idea they want to explore or plan
-- An existing feature plan needs refinement
-- A feature plan needs to be turned into actionable roadmaps
-
-Do NOT use when:
-- Bug fixes (use `bug-analyzer` skill)
-- Simple, well-understood changes that don't need planning
-
-## Procedure: Plan a feature
-
-1. **Gather requirements** — What problem does this solve? Who benefits? What's the expected outcome?
-2. **Analyze scope** — Which modules, routes, models, services are affected?
-3. **Write the plan** — Create a feature plan document (see template below).
-4. **Verify** — Confirm all affected areas are identified, no missing dependencies.
-
-A **feature plan** captures the "what and why" of a feature:
-- Problem it solves, who benefits, expected outcome
-- Scope, affected modules, technical approach
-- Open questions and decisions
-
-A **roadmap** captures the "how and when" — the step-by-step implementation plan.
-Feature plans and roadmaps are linked but separate concerns.
-
-## File structure
-
-```
-agents/features/                         # Project-wide feature plans
-├── {feature-name}.md
-
-app/Modules/{Module}/agents/features/    # Module-scoped feature plans
-├── {feature-name}.md
-
-.augment/templates/
-└── features.md                          # Feature plan template
-```
-
-Roadmaps generated from features live in `agents/roadmaps/` (or module-level `agents/roadmaps/`).
-
-## Feature lifecycle
-
-### Quick workflow (small features)
-
-```
-Explore → Plan → Refine → Roadmap → Implement
-  ↑                ↑
-  └── iterate ─────┘
-```
-
-| Phase | Command | Output |
-|---|---|---|
-| **Explore** | `/feature-explore` | Brainstorming notes, feasibility check, rough scope |
-| **Plan** | `/feature-plan` | Structured feature doc in `agents/features/` |
-| **Refine** | `/feature-refactor` | Updated feature doc with changes |
-| **Roadmap** | `/feature-roadmap` | Roadmap(s) in `agents/roadmaps/`, linked from feature |
-
-### Full workflow (complex features, 7 phases)
-
-Use the full workflow for features that span multiple files, require architecture decisions,
-or have unclear requirements. Trigger with `/feature:dev`.
-
-```
-Discovery → Exploration → Questions → Architecture → Implementation → Review → Summary
-```
-
-#### Phase 1: Discovery
-- Clarify the feature request — what problem does it solve?
-- Identify constraints, requirements, and affected users.
-- **Understanding Lock (Hard Gate):** Summarize understanding in 5–7 bullets covering:
-  what is being built, why, who it's for, key constraints, explicit non-goals.
-- List all **assumptions** explicitly.
-- **Wait for explicit confirmation before proceeding.** Do NOT design until confirmed.
-
-#### Phase 2: Codebase Exploration
-- Search for similar features in the codebase.
-- Map the architecture and abstractions in the affected area.
-- Identify key files, services, models, routes involved.
-- Present findings with file references.
-
-#### Phase 3: Clarifying Questions
-- Review codebase findings against the feature request.
-- Identify underspecified aspects: edge cases, error handling, integrations, backward compatibility.
-- **Non-functional requirements** — explicitly clarify or propose defaults for:
-  - Performance expectations (response time, throughput)
-  - Scale (users, data volume, concurrent requests)
-  - Security / privacy constraints
-  - Reliability / availability needs
-  - Maintenance and ownership expectations
-- Present all questions in an organized list.
-- **Wait for answers before proceeding.**
-
-#### Phase 4: Architecture Design
-- Design 2-3 implementation approaches with different tradeoffs:
-  - **Minimal changes** — smallest change, maximum reuse.
-  - **Clean architecture** — maintainability, elegant abstractions.
-  - **Pragmatic balance** — speed + quality.
-- Present comparison with pros/cons and a recommendation.
-- **Ask the user which approach to use** (present as numbered options).
-
-#### Phase 5: Implementation
-- **Wait for explicit approval** before starting.
-- Follow chosen architecture from Phase 4.
-- Follow codebase conventions strictly.
-- Track progress via task list or roadmap.
-
-#### Phase 6: Quality Review
-- Review the implementation for:
-  - Simplicity, DRY, elegance.
-  - Bugs and correctness.
-  - Convention adherence.
-- Present findings with severity levels.
-- **Ask what to fix now vs. later.**
-
-#### Phase 7: Summary
-- Summarize what was built, key decisions, files modified.
-- Suggest next steps (tests, documentation, follow-up features).
-- Update roadmap if applicable.
-
-## Decision log
-
-Maintain a running **decision log** throughout the planning process. For each decision:
-- What was decided
-- Alternatives considered
-- Why this option was chosen
-
-Include the decision log in the feature plan file under a `## Decisions` section.
-This ensures future developers (and agents) understand the reasoning, not just the outcome.
-
-## Bite-sized task granularity (structural roadmaps only)
-
-When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks ("Add login endpoint", "Update tests") are correct when the work is well-scoped and low-risk.
-
-Structural roadmap tasks must include:
-
-1. **Exact file path** — `app/Modules/Auth/Services/LoginService.php`, never *"the login service"*.
-2. **Complete code** — every method body, import, and signature ready to paste; no `// existing code` ellipses, no `…`.
-3. **Exact command** — the precise CLI invocation, never *"run the migration"*. Examples: `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php` (Laravel), `bin/console doctrine:migrations:migrate --no-interaction` (Symfony), `bin/rails db:migrate VERSION=20260509…` (Rails), `npx prisma migrate deploy` (Prisma), `alembic upgrade +1` (Python / Alembic), `sqlx migrate run` (Rust).
-4. **Expected output** — what success looks like (`Migrated: 2026_05_09_create_logins`) and the exit code.
-5. **No placeholders** — angle-bracket placeholders, `TODO`, `FIXME`, `tbd`, and `???` are blockers; resolve before the task ships.
-
-The complexity flag lives in the roadmap's YAML frontmatter:
-
-```yaml
----
-complexity: structural   # triggers bite-sized granularity
-# or
-complexity: lightweight  # default — skips bite-sized granularity
----
-```
-
-Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Task Structure + § No Placeholders (v5.1.0); complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).
-
-## Self-review (3-scan checklist)
-
-Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.
-
-1. **Spec coverage** — every requirement, AC bullet, or constraint from the input has a corresponding section / AC / scope item in the plan. Walk the input top-to-bottom; tick each requirement against the plan; missing items become open questions or new AC.
-2. **Placeholder / TODO scan** — grep the draft for `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX`. Either resolve them now or surface them in the *Open questions* section. No placeholder ships unflagged.
-3. **Type / shape consistency** — proposed data structures, API shapes, file paths, and module names match existing codebase patterns. Cite at least one existing file per new structure as the convention anchor.
-
-This scan is **separate from** adversarial-review (below). Self-review catches mechanical gaps (missing AC, leftover placeholders, mis-shaped types); adversarial-review challenges the plan's reasoning.
-
-Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
-
-## Adversarial self-review
-
-After the 3-scan self-review passes, run the **`adversarial-review`** skill before presenting.
-Focus on the "Feature plans / Architecture" attack questions. See that skill for the full process.
-
-## Feature plan format
-
-See `.augment/templates/features.md` for the full structure. Key sections:
-
-- **Problem** — What pain point does this solve?
-- **Proposal** — What's the solution?
-- **Scope** — What's in, what's out?
-- **Affected Areas** — Which modules, models, services, routes?
-- **Technical Approach** — High-level architecture decisions
-- **Non-Functional Requirements** — Performance, scale, security, reliability
-- **Decisions** — Decision log with alternatives and reasoning
-- **Open Questions** — Unresolved decisions
-- **Roadmaps** — Links to generated roadmap files
-
-## Integration with other systems
-
-### Sessions
-
-```markdown
-- **Feature:** `agents/features/my-feature.md`
-```
-
-### Roadmaps
-
-Feature plans link to their roadmaps in the `## Roadmaps` section.
-Roadmaps reference their source feature in the `## Context` section.
-
-### Modules
-
-If a feature is scoped to a single module, the feature plan and roadmaps live in the
-module's `agents/` directory:
-- Feature: `app/Modules/{Module}/agents/features/`
-- Roadmaps: `app/Modules/{Module}/agents/roadmaps/`
-
-
-## Behavior rules
-
-### Research before planning
-
-Before creating a feature plan, always:
-1. **Search the codebase** for related code, existing patterns, and affected areas.
-2. **Read module docs** if the feature touches a specific module.
-3. **Check existing features** in `agents/features/` for overlap or dependencies.
-
-### Be collaborative
-
-- **Ask questions** — don't assume requirements.
-- **Challenge scope** — suggest what can be deferred.
-- **Show tradeoffs** — present options with pros/cons.
-- **Validate feasibility** — check if the codebase supports the approach.
-
-### Keep it navigational
-
-Feature plans are decision documents, not implementation guides.
-Implementation details belong in roadmaps.
-
-## Output format
-
-1. Feature plan document following the template structure
-2. Decision log with rationale for key choices
-3. Implementation roadmap with ordered tasks
-
-## Auto-trigger keywords
-
-- feature planning
-- feature exploration
-- feature roadmap
-- requirements
-
-## Gotcha
-
-- Don't plan features without understanding the business context — ask the user before assuming.
-- The model tends to over-engineer plans — start with the simplest viable solution.
-- A plan without acceptance criteria is incomplete — always define what "done" means.
-- Don't create plans for features that already exist — search the codebase first.
-
-## Do NOT
-
-- Do NOT create feature plans without user input — always collaborate.
-- Do NOT skip codebase research — always check what exists.
-- Do NOT put implementation steps in the feature plan — that's the roadmap's job.
-- Do NOT commit or push without permission.
-- Do NOT duplicate information from `AGENTS.md` or module docs.

package/.agent-src/skills/flux/SKILL.md

@@ -1,121 +0,0 @@
----
-model_tier: medium
-name: flux
-description: "Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives."
-domain: engineering
-workspaces:
-  - engineering
-packs:
-  - laravel
-trust:
-  level: professional
-install:
-  default: false
-  removable: true
----
-
-# flux
-
-## Positioning — dispatched, not standalone
-
-`flux` is the **primitive-library executor** for projects on the
-Livewire + Flux stack. It is invoked by
-[`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
-once the design brief is locked, and revisited by `review.py` /
-`polish.py` during the design-review loop. It does **not** own the
-flow, does **not** drive the audit, and does **not** lock the design.
-
-| Concern | Owner |
-|---|---|
-| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
-| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
-| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
-| Component logic / state / actions | [`livewire`](../livewire/SKILL.md) |
-| Static Blade partials | [`blade-ui`](../blade-ui/SKILL.md) |
-
-## When to use
-
-Cite this skill when:
-
-- The project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
-- Building forms, modals, dropdowns, toasts, or other standard UI elements that Flux already provides
-
-Do NOT use when:
-
-- Raw Blade templates without Flux (use `blade-ui` skill)
-- Livewire component logic / state (use `livewire` skill)
-- React + shadcn (use `react-shadcn-ui` skill)
-- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
-
-## Procedure: Create a Flux view
-
-### Step 0: Inspect
-
-1. Confirm Flux is installed — check `composer.json` for `livewire/flux`.
-2. Check existing views — match Flux component usage patterns.
-3. Check Flux docs — https://fluxui.dev/docs for latest API.
-
-### Step 1: Build the view
-
-1. Use `<flux:*>` components instead of raw HTML.
-2. Use `variant` prop for styling (not custom Tailwind for standard styles).
-3. Use `wire:model` for Livewire binding.
-4. Use `label` prop on form fields (accessibility).
-
-### Step 2: Validate
-
-1. No raw HTML form elements where Flux equivalents exist.
-2. No manual error rendering (Flux has built-in validation display).
-3. No conflicting Tailwind classes overriding Flux styles.
-
-## Conventions
-
-→ See guideline `php/flux.md` for component reference, variants, forms, icons.
-
-## Output format
-
-1. Blade view using Flux components with correct props and slots
-2. Livewire component class if interactive behavior is needed
-
-### Review pass — a11y findings + preview envelope
-
-When this skill is dispatched by `directives/ui/review.py` (test slot)
-or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
-not the initial apply — it also emits:
-
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
-  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
-  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
-  pre-existing entries on replay. Omit the envelope on apply passes; the
-  engine's `_apply_a11y_gate` only fires when a baseline is present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
-  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
-  populated triggers the `preview_render_failed` halt; `render_ok: true`
-  with `screenshot_path` threads the screenshot into the delivery
-  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
-  a consumer-project dependency — this package does not ship one.
-
-Polish dispatch: when the dispatcher skips `review` because a previous
-review pass already returned `SUCCESS`, this skill MUST itself
-synthesise the updated `state.ui_review.findings` (including any
-remaining `a11y_violation` entries) so the engine's gate sees the
-current state on the next polish round.
-
-## Gotcha
-
-- The model tends to use old Flux API syntax — always check latest docs.
-- Flux has built-in validation display — don't add manual error rendering alongside it.
-- Don't mix Flux with raw HTML form elements in the same form.
-
-## Do NOT
-
-- Do NOT use raw `<input>`, `<select>`, `<button>` when Flux equivalents exist.
-- Do NOT override Flux styles with conflicting Tailwind — use variants or slots.
-- Do NOT skip the `label` prop on form fields — accessibility.
-
-## Auto-trigger keywords
-
-- Flux UI
-- Livewire components
-- Flux component
-- Laravel Flux

package/.agent-src/skills/jira-integration/SKILL.md

@@ -1,187 +0,0 @@
----
-model_tier: medium
-name: jira-integration
-description: "Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking."
-domain: process
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# Jira Skill
-
-## When to use
-
-Use this skill when:
-- Reading a Jira ticket for context (bug reports, feature requests)
-- Creating new Jira issues from discovered bugs or planned work
-- Transitioning ticket status (e.g., "In Progress" → "In Review")
-- Writing JQL queries to find related issues
-- Linking branches or PRs to Jira tickets
-
-
-Do NOT use when:
-- GitHub Issues (use `github-api` tool directly)
-- Linear or other issue trackers
-
-## Procedure: Work with Jira
-
-1. **Identify action** — Search, read, create, update, or transition a ticket?
-2. **Use the correct endpoint** — See API table below.
-3. **Execute** — Make the API call with required fields.
-4. **Verify** — Confirm the response contains expected data or the ticket was updated.
-
-| Tool | Purpose |
-|---|---|
-| `jira-integration` (GET `/search/jql`) | Search issues with JQL |
-| `jira-integration` (GET `/issue/{key}`) | Read a specific ticket |
-| `jira-integration` (POST `/issue`) | Create a new ticket |
-| `jira-integration` (PUT `/issue/{key}`) | Update a ticket |
-| `jira-integration` (GET `/issue/{key}/transitions`) | Get available status transitions |
-| `jira-integration` (POST `/issue/{key}/transitions`) | Transition ticket status |
-| `jira-integration` (POST `/issue/{key}/comment`) | Add a comment |
-| `jira-integration` (GET `/project`) | List projects |
-| `jira-integration` (GET `/field`) | List available fields (check before writing JQL) |
-
-## Branch-to-ticket detection
-
-Extract ticket IDs from branch names automatically:
-
-```
-feat/DEV-1234/user-notifications  →  DEV-1234
-fix/DEV-5678/null-pointer         →  DEV-5678
-hotfix/DEV-999/critical-fix       →  DEV-999
-```
-
-Pattern: `[A-Z]+-[0-9]+` anywhere in the branch name.
-
-Use `git branch --show-current` to detect, then fetch the ticket:
-
-```
-jira GET /issue/DEV-1234
-```
-
-## JQL patterns
-
-### Common queries
-
-```jql
-# My open tickets
-assignee = currentUser() AND status != Done ORDER BY priority DESC
-
-# Tickets in current sprint
-project = DEV AND sprint in openSprints() AND assignee = currentUser()
-
-# Recently updated bugs
-project = DEV AND type = Bug AND updated >= -7d ORDER BY updated DESC
-
-# Tickets by component
-project = DEV AND component = "Import" AND status != Done
-```
-
-### Tips
-
-- Always check available fields first: `GET /field`
-- Use `currentUser()` for the authenticated user
-- Use `sprint in openSprints()` for current sprint
-- JQL is case-insensitive for field names but case-sensitive for values
-
-## Creating tickets
-
-### Required fields
-
-Always check issue types first: `GET /issue/createmeta/{project}/issuetypes`
-
-Minimum fields for creation:
-- `project` — project key (e.g., `DEV`)
-- `issuetype` — issue type (Bug, Task, Story, etc.)
-- `summary` — short title
-
-### Description format (ADF)
-
-Jira uses Atlassian Document Format for descriptions:
-
-```json
-{
-  "version": 1,
-  "type": "doc",
-  "content": [
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "text": "Description text here." }
-      ]
-    }
-  ]
-}
-```
-
-### Attribution
-
-Always add attribution when creating issues or comments:
-
-```
-Co-authored by Augment Code
-```
-
-With link to `https://www.augmentcode.com/?utm_source=atlassian&utm_medium=jira_issue&utm_campaign=jira`
-
-## Status transitions
-
-Before transitioning, always get available transitions first:
-
-```
-GET /issue/DEV-1234/transitions
-```
-
-Then transition with the correct ID:
-
-```json
-POST /issue/DEV-1234/transitions
-{ "transition": { "id": "31" } }
-```
-
-**Important:** Never transition without explicit user permission (see `rules/no-commit.md` — same principle applies to ticket status changes).
-
-## Linking to PRs
-
-When creating PRs, include the Jira ticket in:
-- **Branch name:** `feat/DEV-1234/description`
-- **PR title:** `feat(DEV-1234): description`
-- **PR description:** Link to the ticket
-
-## Related
-
-- **Skill:** `bug-analyzer` — uses Jira as input source for bug investigation
-- **Skill:** `feature-planning` — uses Jira for feature context
-- **Command:** `/bug-investigate` — auto-detects Jira tickets from branch
-- **Command:** `/feature-plan` — auto-detects Jira tickets from branch
-- **Rule:** `no-commit.md` — never change ticket status without permission
-
-
-## Output format
-
-1. Jira ticket data presented in structured format
-2. Ticket key, summary, status, and relevant fields
-
-## Gotcha
-
-- Jira field names are case-sensitive in JQL — `status` works, `Status` doesn't.
-- Don't create duplicate tickets — always search first with JQL before creating.
-- The model tends to forget that Jira description uses ADF (Atlassian Document Format), not Markdown.
-- `accountId` is required for assignee — display name alone doesn't work in the API.
-
-## Do NOT
-
-- Do NOT change ticket status without explicit user permission.
-- Do NOT create tickets without checking for duplicates.
-
-## Auto-trigger keywords
-
-- Jira
-- ticket
-- issue
-- JQL
-- workflow transition
-- sprint

package/.agent-src/skills/lint-skills/SKILL.md

@@ -1,95 +0,0 @@
----
-model_tier: medium
-name: lint-skills
-description: "Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata."
-domain: process
-execution:
-  type: assisted
-  handler: shell
-  timeout_seconds: 120
-  allowed_tools: []
-  command:
-    - python3
-    - scripts/skill_linter.py
-    - "--all"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# lint-skills
-
-## When to use
-
-Use this skill when:
-
-- Validating the shape of every skill and rule in `.agent-src.uncondensed/`
-- Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
-- Checking locally before opening a PR that CI's skill-lint job will pass
-- Investigating a reported linter failure on a specific skill or rule
-
-Do NOT use when:
-
-- Linting only one file — call `python3 scripts/skill_linter.py <path>` directly
-- Checking cross-references between files — use `check-refs` instead
-- Checking condensation freshness — use `bash scripts/condense.sh --check` instead
-
-## Procedure
-
-### 1. Inspect the environment
-
-Confirm `python3` is available and the working directory is the agent-config
-repository root — the linter expects to find `.agent-src.uncondensed/skills/`
-and related directories relative to `cwd`.
-
-### 2. Dispatch via the runtime layer
-
-Invoke the skill through the runtime dispatcher so the `execution:` block in
-this skill's frontmatter governs the call:
-
-```bash
-python3 scripts/runtime_dispatcher.py run --skill lint-skills
-```
-
-The dispatcher resolves the request, the shell handler runs
-`python3 scripts/skill_linter.py --all`, captures stdout/stderr, and returns
-a typed `ExecutionResult`.
-
-### 3. Verify the result
-
-Check the returned `ExecutionResult`:
-
-- `status: success` and `exit_code: 0` → all skills and rules are clean
-- `exit_code: 1` → warnings only — review `stdout` for the listed warnings
-- `exit_code: 2` → errors present — fix the flagged files before continuing
-- `status: timeout` → the linter exceeded `timeout_seconds` — investigate
-- `status: error` → the interpreter could not launch — check that `python3`
-  is on `PATH` and the repository root is the current working directory
-
-## Output format
-
-1. One-line summary: `success | failure | timeout | error`, exit code,
-   duration in milliseconds
-2. Count of skills and rules the linter inspected, if known
-3. List of files with errors (first 10), each with code and message
-4. Next action: fix errors, re-run, or surface the raw `stdout` for review
-
-## Gotchas
-
-- The command uses `--all`, which walks the full tree — expect several seconds
-  of runtime on a warm repo; bump `timeout_seconds` if the repo has grown
-- Running outside the agent-config repo root will make the linter report zero
-  skills, which looks like a pass but is actually a no-op
-- Warnings (`exit_code: 1`) do not fail CI by default; do not dismiss them as
-  "green" when the task is to get to zero warnings
-
-## Do NOT
-
-- Do NOT invoke `scripts/skill_linter.py` directly when the intent is to test
-  the runtime path — use the dispatcher so the handler and result object are
-  exercised
-- Do NOT raise `timeout_seconds` to hide a genuinely slow linter pass —
-  investigate the slowdown first
-- Do NOT add shell redirection or pipes to `command` — the handler runs
-  `subprocess.run` with `shell=False`; only argv form is supported