argos-harness 0.1.0

package/assets/skills/dashboard-ia/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: dashboard-ia
+description: Information architecture for operator/admin tools — entity-centric, dense, action-fast. Trigger: dashboard IA, admin panel information architecture, back-office UX, operator tool layout, organize a dashboard, admin navigation.
+---
+
+# Dashboard Information Architecture
+
+## Activation Contract
+
+Apply when structuring an admin / back-office / operator tool — where staff manage the records end users consume. For consumer products (web or mobile), use `app-ia` instead; the register is different.
+
+## Hard Rules
+
+- **Organize by ENTITY, not by action.** The operator thinks in records ("this customer"), not verbs ("payments"). A roster row opens the record's DETAIL page; every action on that record (edit, charge, promote, deactivate) lives on its detail — never on a separate action-page that forces re-finding the record.
+- **See state, then act.** The landing view surfaces what needs attention (overdue, pending, failures) with quick counts — not an empty welcome screen.
+- **Density over drama.** Tables are the primary surface: sortable, filterable, paginated, with real empty/loading/error states. Restrained register — no delight motion.
+- **Status is computed, never hand-typed** — derive from domain rules, render as a Badge.
+- **Selection from a growing set is searchable** (combobox), never a plain dropdown.
+- **Always show the current operator** (identity + sign-out) so no one acts on the wrong account.
+- **Enforcement is server-side.** Hiding a button is convenience; back every permission with a real policy.
+- **Omit dead ends.** If an operator lacks read permission for an entity, remove it from the navigation entirely. "Access Denied" empty states should only catch direct URL navigation, never normal click paths.
+- **Global search is mandatory.** Power users bypass click-navigation. Provide a global search or command palette (`Cmd + K`) to jump directly to a record's detail hub using unique identifiers (ID, email, reference number).
+- **Sub-entities live inside the parent.** If a record has heavy 1-to-many relationships (e.g., a customer's payment history), organize them via tabs or sub-routes within the parent's detail page (e.g., `/customers/[id]/payments`). Never create floating, disconnected pages for dependent records.
+
+## Decision Gates
+
+| Situation                                     | Structure                                                     |
+| ---------------------------------------------- | --------------------------------------------------------------- |
+| Acting on one record                          | Its detail page — actions inline                              |
+| Acting on multiple records at once            | Table selection + Bulk action bar + Impact confirmation modal |
+| Seeing activity across all records            | A read-only global log/table                                  |
+| Deep 1-to-many relationships (child entities) | Tabs or sub-routes within the parent entity's detail hub      |
+| A closed fixed set (≤7, never grows)          | Plain select                                                  |
+| A growing set (records, people)               | Searchable combobox                                           |
+| Destructive / irreversible                    | Confirm step; prefer append-only correction                   |
+
+## Execution Steps
+
+1. List the core ENTITIES; make each one's detail the hub for its actions + history.
+2. Make the landing an at-a-glance "needs attention" view that links into the relevant detail.
+3. Map every nav item to an entity or an overview — never to a verb.
+4. Push business rules to a shared layer; the dashboard reads/writes, it does not redefine them.
+5. Map out batch operations early (e.g., bulk approvals, reassignments); handle them on the landing table via row selection, followed by a summary confirmation step.
+6. Structure nested routing to strictly reflect your database hierarchy (e.g., `/entities/:id/sub-entities`) so URLs remain shareable and preserve context.
+
+## Output Contract
+
+An IA where: nav items are entities/overviews (not actions), each record has one detail hub, the landing shows state first, and no flow forces re-selecting a record you already had.
+
+## References
+
+- Complement: `app-ia` for consumer products. Build-time stack specifics for a dashboard's data-table, filters, and bulk-action components are a build-phase concern, not an IA one — resolve them against the repo's actual UI kit at build time.
+
+_Adapted from a skill originally authored by ricardomarin._

package/assets/skills/django-drf/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: django-drf
+description: Django REST Framework patterns. Trigger: When building REST APIs with Django - ViewSets, Serializers, Filters.
+---
+
+## ViewSet Pattern
+
+```python
+from rest_framework import viewsets, status
+from rest_framework.response import Response
+from rest_framework.decorators import action
+
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+    filterset_class = UserFilter
+    permission_classes = [IsAuthenticated]
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return UserCreateSerializer
+        if self.action in ["update", "partial_update"]:
+            return UserUpdateSerializer
+        return UserSerializer
+
+    @action(detail=True, methods=["post"])
+    def activate(self, request, pk=None):
+        user = self.get_object()
+        user.is_active = True
+        user.save()
+        return Response({"status": "activated"})
+```
+
+## Serializer Patterns
+
+```python
+from rest_framework import serializers
+
+# Read Serializer
+class UserSerializer(serializers.ModelSerializer):
+    full_name = serializers.SerializerMethodField()
+
+    class Meta:
+        model = User
+        fields = ["id", "email", "full_name", "created_at"]
+        read_only_fields = ["id", "created_at"]
+
+    def get_full_name(self, obj):
+        return f"{obj.first_name} {obj.last_name}"
+
+# Create Serializer
+class UserCreateSerializer(serializers.ModelSerializer):
+    password = serializers.CharField(write_only=True)
+
+    class Meta:
+        model = User
+        fields = ["email", "password", "first_name", "last_name"]
+
+    def create(self, validated_data):
+        password = validated_data.pop("password")
+        user = User(**validated_data)
+        user.set_password(password)
+        user.save()
+        return user
+
+# Update Serializer
+class UserUpdateSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["first_name", "last_name"]
+```
+
+## Filters
+
+```python
+from django_filters import rest_framework as filters
+
+class UserFilter(filters.FilterSet):
+    email = filters.CharFilter(lookup_expr="icontains")
+    is_active = filters.BooleanFilter()
+    created_after = filters.DateTimeFilter(
+        field_name="created_at",
+        lookup_expr="gte"
+    )
+    created_before = filters.DateTimeFilter(
+        field_name="created_at",
+        lookup_expr="lte"
+    )
+
+    class Meta:
+        model = User
+        fields = ["email", "is_active"]
+```
+
+## Permissions
+
+```python
+from rest_framework.permissions import BasePermission
+
+class IsOwner(BasePermission):
+    def has_object_permission(self, request, view, obj):
+        return obj.owner == request.user
+
+class IsAdminOrReadOnly(BasePermission):
+    def has_permission(self, request, view):
+        if request.method in ["GET", "HEAD", "OPTIONS"]:
+            return True
+        return request.user.is_staff
+```
+
+## Pagination
+
+```python
+from rest_framework.pagination import PageNumberPagination
+
+class StandardPagination(PageNumberPagination):
+    page_size = 20
+    page_size_query_param = "page_size"
+    max_page_size = 100
+
+# settings.py
+REST_FRAMEWORK = {
+    "DEFAULT_PAGINATION_CLASS": "api.pagination.StandardPagination",
+}
+```
+
+## URL Routing
+
+```python
+from rest_framework.routers import DefaultRouter
+
+router = DefaultRouter()
+router.register(r"users", UserViewSet, basename="user")
+router.register(r"posts", PostViewSet, basename="post")
+
+urlpatterns = [
+    path("api/v1/", include(router.urls)),
+]
+```
+
+## Testing
+
+```python
+import pytest
+from rest_framework import status
+from rest_framework.test import APIClient
+
+@pytest.fixture
+def api_client():
+    return APIClient()
+
+@pytest.fixture
+def authenticated_client(api_client, user):
+    api_client.force_authenticate(user=user)
+    return api_client
+
+@pytest.mark.django_db
+class TestUserViewSet:
+    def test_list_users(self, authenticated_client):
+        response = authenticated_client.get("/api/v1/users/")
+        assert response.status_code == status.HTTP_200_OK
+
+    def test_create_user(self, authenticated_client):
+        data = {"email": "new@test.com", "password": "pass123"}
+        response = authenticated_client.post("/api/v1/users/", data)
+        assert response.status_code == status.HTTP_201_CREATED
+```
+
+## Commands
+
+```bash
+python manage.py runserver
+python manage.py makemigrations
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py shell
+```
+
+## Keywords
+django, drf, rest framework, viewset, serializer, api, rest api

package/assets/skills/go-testing/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: go-testing
+description: Apply focused Go testing patterns. Trigger: Go tests, go test coverage, Bubbletea teatest, golden files.
+---
+
+## Activation Contract
+
+Load this skill when writing or reviewing Go tests, adding coverage, testing Bubbletea/TUI flows, using `teatest`, or updating golden files.
+
+## Hard Rules
+
+- Prefer table-driven tests for multiple cases; use `t.Run(tt.name, ...)`.
+- Test behavior and state transitions, not implementation trivia.
+- Use `t.TempDir()` for filesystem tests; never rely on a real home directory.
+- Keep integration tests skippable with `testing.Short()` when they run external commands or slow flows.
+- For Bubbletea, test `Model.Update()` directly for state changes; use `teatest` only for interactive flows.
+- Golden files must be deterministic; update only through the repo's `-update` path and rerun tests without `-update`.
+- Use small mocks/interfaces around system or command execution boundaries.
+
+## Decision Gates
+
+| Target | Test pattern |
+|---|---|
+| Pure function or parser | Table-driven unit test. |
+| Error behavior | Explicit success and failure cases. |
+| File operations | `t.TempDir()` plus focused assertions. |
+| TUI state transition | Direct `Model.Update()` call with `tea.Msg`. |
+| Full TUI interaction | `teatest.NewTestModel()`. |
+| Rendered output | Golden file test. |
+| Real external command | Integration test; skip in `-short`. |
+
+## Execution Steps
+
+1. Identify behavior under test and the smallest public boundary that proves it.
+2. Choose the test pattern from the decision gate.
+3. Name cases by scenario, not input mechanics.
+4. Assert outputs, errors, state, and side effects explicitly.
+5. Run the narrow package test first, then the relevant broader suite.
+6. For golden updates: run with `-update`, inspect diff, then rerun without `-update`.
+
+## Output Contract
+
+Report test files changed, scenarios covered, commands executed, golden files updated, and any skipped integration scope.
+
+## References
+
+- [references/examples.md](references/examples.md) — compact table-driven, Bubbletea, teatest, golden, and command examples.

package/assets/skills/go-testing/references/examples.md

@@ -0,0 +1,89 @@
+# Go Testing Examples
+
+## Table-Driven Test
+
+```go
+func TestProcessInput(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   string
+        want    string
+        wantErr bool
+    }{
+        {name: "valid input", input: "hello", want: "HELLO"},
+        {name: "empty input", input: "", wantErr: true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got, err := ProcessInput(tt.input)
+            if (err != nil) != tt.wantErr {
+                t.Fatalf("err = %v, wantErr %v", err, tt.wantErr)
+            }
+            if got != tt.want {
+                t.Fatalf("got %q, want %q", got, tt.want)
+            }
+        })
+    }
+}
+```
+
+## Bubbletea State Transition
+
+```go
+func TestModelUpdateEnter(t *testing.T) {
+    m := NewModel()
+    next, _ := m.Update(tea.KeyMsg{Type: tea.KeyEnter})
+    got := next.(Model)
+    if got.Screen != ScreenMainMenu {
+        t.Fatalf("screen = %v, want %v", got.Screen, ScreenMainMenu)
+    }
+}
+```
+
+## Teatest Flow
+
+```go
+func TestInteractiveFlow(t *testing.T) {
+    tm := teatest.NewTestModel(t, NewModel())
+    tm.Send(tea.KeyMsg{Type: tea.KeyEnter})
+    tm.WaitFinished(t, teatest.WithDuration(time.Second))
+    final := tm.FinalModel(t).(Model)
+    if final.Screen != ExpectedScreen {
+        t.Fatalf("screen = %v, want %v", final.Screen, ExpectedScreen)
+    }
+}
+```
+
+## Golden File Pattern
+
+```go
+var update = flag.Bool("update", false, "update golden files")
+
+func assertGolden(t *testing.T, path string, got string) {
+    t.Helper()
+    if *update {
+        if err := os.WriteFile(path, []byte(got), 0o644); err != nil {
+            t.Fatal(err)
+        }
+    }
+    want, err := os.ReadFile(path)
+    if err != nil {
+        t.Fatal(err)
+    }
+    if got != string(want) {
+        t.Fatalf("golden mismatch for %s", path)
+    }
+}
+```
+
+## Commands
+
+```bash
+go test ./...
+go test -v ./internal/tui/...
+go test -run TestNavigation ./internal/tui
+go test -cover ./...
+go test ./internal/components -update
+go test -short ./...
+```

package/assets/skills/issue-creation/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: issue-creation
+description: Create issues with issue-first checks. Trigger: creating GitHub issues, bug reports, or feature requests.
+---
+
+## When to Use
+
+Use this skill when:
+- Creating a GitHub issue (bug report or feature request)
+- Helping a contributor file an issue
+- Triaging or approving issues as a maintainer
+
+---
+
+## Critical Rules
+
+1. **Blank issues are disabled** — MUST use a template (bug report or feature request)
+2. **Every issue gets `status:needs-review` automatically** on creation
+3. **A maintainer MUST add `status:approved`** before any PR can be opened
+4. **Questions go to your project's own Discussions tab (or equivalent support channel)**, not issues — don't point contributors at a foreign repo's discussions
+
+---
+
+## Workflow
+
+```
+1. Search existing issues for duplicates
+2. Choose the correct template (Bug Report or Feature Request)
+3. Fill in ALL required fields
+4. Check pre-flight checkboxes
+5. Submit → issue gets status:needs-review automatically
+6. Wait for maintainer to add status:approved
+7. Only then open a PR linking this issue
+```
+
+---
+
+## Issue Templates
+
+### Bug Report
+
+Template: `.github/ISSUE_TEMPLATE/bug_report.yml`
+Auto-labels: `bug`, `status:needs-review`
+
+#### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| **Pre-flight Checks** | Checkboxes: no duplicate + understands approval workflow |
+| **Bug Description** | Clear description of the bug |
+| **Steps to Reproduce** | Numbered steps to reproduce |
+| **Expected Behavior** | What should have happened |
+| **Actual Behavior** | What happened instead (include errors/logs) |
+| **Operating System** | Dropdown: macOS, Linux variants, Windows, WSL |
+| **Agent / Client** | Dropdown: Claude Code, OpenCode, Gemini CLI, Cursor, Windsurf, Codex, Other |
+| **Shell** | Dropdown: bash, zsh, fish, Other |
+
+#### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| **Relevant Logs** | Log output (auto-formatted as code block) |
+| **Additional Context** | Screenshots, workarounds, extra info |
+
+#### Example — Bug Report via CLI
+
+```bash
+gh issue create --template "bug_report.yml" \
+  --title "fix(scripts): setup.sh fails on zsh with glob error" \
+  --body "
+### Pre-flight Checks
+- [x] I have searched existing issues and this is not a duplicate
+- [x] I understand this issue needs status:approved before a PR can be opened
+
+### Bug Description
+Running setup.sh on zsh throws a glob error when no matching files exist.
+
+### Steps to Reproduce
+1. Clone the repo
+2. Run \`./scripts/setup.sh\` in zsh
+3. See error: \`zsh: no matches found: skills/*\`
+
+### Expected Behavior
+The script should handle missing glob matches gracefully.
+
+### Actual Behavior
+Script crashes with glob error.
+
+### Operating System
+macOS
+
+### Agent / Client
+Claude Code
+
+### Shell
+zsh
+
+### Relevant Logs
+\`\`\`
+zsh: no matches found: skills/*
+\`\`\`
+"
+```
+
+---
+
+### Feature Request
+
+Template: `.github/ISSUE_TEMPLATE/feature_request.yml`
+Auto-labels: `enhancement`, `status:needs-review`
+
+#### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| **Pre-flight Checks** | Checkboxes: no duplicate + understands approval workflow |
+| **Problem Description** | The pain point this feature solves |
+| **Proposed Solution** | How it should work from the user's perspective |
+| **Affected Area** | Dropdown: Scripts, Skills, Examples, Documentation, CI/Workflows, Other |
+
+#### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| **Alternatives Considered** | Other approaches or workarounds |
+| **Additional Context** | Mockups, examples, references |
+
+#### Example — Feature Request via CLI
+
+```bash
+gh issue create --template "feature_request.yml" \
+  --title "feat(scripts): add Codex support to setup.sh" \
+  --body "
+### Pre-flight Checks
+- [x] I have searched existing issues and this is not a duplicate
+- [x] I understand this issue needs status:approved before a PR can be opened
+
+### Problem Description
+The setup script only configures Claude Code, Gemini CLI, and OpenCode. Codex users have to manually copy skills.
+
+### Proposed Solution
+Add a Codex option to setup.sh that links skills to the .codex/ directory.
+
+Example:
+\`\`\`bash
+./scripts/setup.sh --agent codex
+\`\`\`
+
+### Affected Area
+Scripts (setup, installation)
+
+### Alternatives Considered
+Manually symlinking, but that defeats the purpose of the setup script.
+"
+```
+
+---
+
+## Label System
+
+### Applied Automatically on Issue Creation
+
+| Template | Labels added |
+|----------|-------------|
+| Bug Report | `bug`, `status:needs-review` |
+| Feature Request | `enhancement`, `status:needs-review` |
+
+### Applied by Maintainers
+
+| Label | When to apply |
+|-------|--------------|
+| `status:approved` | Issue accepted for implementation — PRs can now be opened |
+| `priority:high` | Critical bug or urgent feature |
+| `priority:medium` | Important but not blocking |
+| `priority:low` | Nice to have |
+
+---
+
+## Maintainer Approval Workflow
+
+```
+1. New issue arrives with status:needs-review
+2. Review the issue — is it valid, clear, and in scope?
+3. If YES → add status:approved label
+4. If NO → comment with reason, close if needed
+5. Contributor can now open a PR linking this issue
+```
+
+---
+
+## Decision Tree
+
+```
+Is it a bug?                    → Use Bug Report template
+Is it a new feature/improvement? → Use Feature Request template
+Is it a question?               → Use your project's Discussions (or equivalent), NOT issues
+Is it a duplicate?              → Link to existing issue, close
+```
+
+---
+
+## Commands
+
+```bash
+# Search existing issues before creating
+gh issue list --search "keyword"
+
+# Create bug report
+gh issue create --template "bug_report.yml" --title "fix(scope): description"
+
+# Create feature request
+gh issue create --template "feature_request.yml" --title "feat(scope): description"
+
+# Maintainer: approve an issue
+gh issue edit <number> --add-label "status:approved"
+
+# Maintainer: add priority
+gh issue edit <number> --add-label "priority:high"
+```
+
+---
+
+_Adapted from a skill originally authored by gentleman-programming._