@prateek_ai/agents-maker 1.0.0

package/skills/review_code.md

@@ -0,0 +1,83 @@
+# Skill: review_code
+
+## Description
+
+Perform a structured code review of one or more file snippets. Return a severity-rated issue table covering correctness, security, performance, readability, and test coverage. Each finding includes file:line, issue description, and a concrete recommendation.
+
+---
+
+## When to invoke
+
+- The Code Agent is asked to review or critique existing code.
+- The Orchestrator routes a "review this PR" or "audit this file" request.
+- A refactoring task requires a baseline assessment before changes.
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `files` | Yes | One or more file snippets with paths |
+| `review_focus` | No | One or more of: `security`, `performance`, `correctness`, `readability`, `test_coverage`, `all` (default: `all`) |
+| `language` | No | Programming language (inferred from file extension if omitted) |
+| `context` | No | Brief description of what the code does, to avoid false positives |
+
+**If required input is missing:**
+- `files` — ask: "Please paste the code files or snippets you want reviewed." Do not produce a review without actual code.
+- `review_focus` — default to `all`; note this in the output summary line.
+- `language` — infer from file extension or code syntax; if indeterminate, note "Language inferred as [X] — correct if wrong."
+- `context` — proceed without it; note any assumptions made about the code's purpose in the Positive Findings section.
+
+---
+
+## Output format
+
+```
+## Code Review: <file(s) reviewed>
+
+**Summary**: N critical, N high, N medium, N low, N info
+
+| Severity | File:Line | Category | Issue | Recommendation |
+|---|---|---|---|---|
+| critical | auth.py:47 | security | SQL query built via string concat | Use parameterized queries |
+| high | user_service.py:112 | correctness | `get_user()` returns None without handling | Add None check or raise a typed exception |
+| medium | utils.py:23 | performance | List comprehension inside tight loop | Pre-compute outside the loop |
+| low | models.py:8 | readability | Variable name `d` is ambiguous | Rename to `user_data` |
+| info | api.py:55 | test_coverage | No test covers the 404 path | Add a test case for missing resource |
+
+## Positive Findings
+- <bullet: what is done well — not just issues>
+
+## Out of scope
+- <bullet: anything noticed but not within the requested review_focus>
+```
+
+---
+
+## Severity definitions
+
+| Severity | Meaning |
+|---|---|
+| `critical` | Bug, security vulnerability, or data corruption risk in production |
+| `high` | Likely to cause incorrect behavior under normal conditions |
+| `medium` | Degraded performance, poor error handling, or maintainability risk |
+| `low` | Style, naming, or minor readability issue |
+| `info` | Observation or suggestion; no action required |
+
+---
+
+## Token cost tier
+
+**Medium.** Scales with number of files. Typical output per 100-line file: 200–400 tokens.
+
+Compression hint: for large codebases, filter to `review_focus: security` or `review_focus: correctness` to reduce output. Ask the requester which categories matter most.
+
+---
+
+## Notes
+
+- Always include at least one "Positive Findings" item. Reviews with no positive findings tend to be ignored.
+- `[SECURITY]` findings must be present in the table even if `review_focus` does not include security — security is never optional.
+- Do not flag style issues as `high` or `critical`. Enforce severity discipline.
+- If a file has no issues, return: "No findings for `<file>` at the requested severity level."

package/skills/review_layout.md

@@ -0,0 +1,89 @@
+# Skill: review_layout
+
+## Description
+
+Critique the visual hierarchy, spacing, responsive behavior, and accessibility of a UI layout. Input can be a component tree, file snippet, or plain-text screen description. Output is a structured table of findings with severity and specific recommendations.
+
+---
+
+## When to invoke
+
+- The UI Agent needs a baseline assessment before making layout recommendations.
+- The UX Agent identifies a layout-level problem (not a flow problem) and defers it.
+- A design review specifically calls out visual or accessibility issues.
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `screen_description` | Yes | Component tree, file snippet, or plain-text description of the layout |
+| `framework` | No | `React` \| `Vue` \| `HTML/CSS` \| `Svelte` \| `other` |
+| `target_devices` | No | `desktop` \| `mobile` \| `both` (default: `both`) |
+| `accessibility_level` | No | `A` \| `AA` \| `AAA` \| `none` (default: `AA`) |
+| `existing_tokens` | No | Design token values in scope (colors, spacing scale) |
+
+**If required input is missing:**
+- `screen_description` — ask: "Please paste a component tree, file snippet, or describe the layout you want reviewed." Do not produce findings without it.
+- `framework` — infer from component syntax (JSX → React, SFC → Vue, `.svelte` → Svelte); if indeterminate, note "Framework assumed: [X] — correct if wrong."
+- `target_devices` — default to `both`.
+- `accessibility_level` — default to `AA`.
+- `existing_tokens` — proceed without; note that token-specific recommendations (e.g., "use spacing-4") cannot be made and generic values will be suggested instead.
+
+---
+
+## Output format
+
+```
+## Layout Review: <screen/component name>
+
+**Summary**: N critical, N high, N medium, N low
+
+### Visual Hierarchy
+
+| Severity | Element | Issue | Recommendation |
+|---|---|---|---|
+| high | Page title | Same font size as body text | Increase to heading level; use h1 |
+| medium | CTA button | Low contrast against background | Use primary brand color |
+
+### Spacing
+
+| Severity | Element | Issue | Recommendation |
+|---|---|---|---|
+| medium | Card grid | Inconsistent gap (12px and 16px mixed) | Standardize to spacing-4 (16px) |
+
+### Responsive Behavior
+
+| Severity | Breakpoint | Issue | Recommendation |
+|---|---|---|---|
+| high | Mobile (<768px) | Table overflows viewport | Use horizontal scroll or card layout |
+
+### Accessibility
+
+| Severity | Element | WCAG criterion | Issue | Fix |
+|---|---|---|---|---|
+| critical | Icon button | 1.1.1 Non-text content | No aria-label | Add `aria-label="<action>"` |
+| high | Link color | 1.4.3 Contrast | 2.8:1 ratio (AA requires 4.5:1) | Darken link color |
+
+### Positive Findings
+- <bullet>
+```
+
+Omit sections with no findings.
+
+---
+
+## Token cost tier
+
+**Low.** Typical output: 200–400 tokens. Does not require reading large file trees.
+
+Compression hint: if scoped to a single component, this skill is already token-light. No further compression needed.
+
+---
+
+## Notes
+
+- WCAG criterion references should use the format `N.N.N Title`.
+- Do not flag every spacing inconsistency as `high`. Reserve `high` for issues that visually break the layout or prevent task completion.
+- If the input is text-only (no actual CSS/tokens), note: "Review based on description only — actual values may differ."

package/skills/suggest_next.md

@@ -0,0 +1,105 @@
+# Skill: Suggest Next Steps
+
+## Purpose
+
+After completing any deliverable — an approved artifact, an approved increment, or any answer to a
+user question — surface three concrete, prioritized next moves so the user always knows what to do
+without having to think about it.
+
+This skill fires **automatically** at the end of every response when Companion Mode is active.
+It may also be invoked on demand: "what should I do next?" / "what's next?" / "options?"
+
+---
+
+## Trigger Conditions
+
+- After every approved phase artifact (`task_profile`, `requirements_spec`, `solution_design`,
+  `work_product`, `refinement_report`, `handoff_package`)
+- After every approved implementation increment in the `build_log`
+- When the user explicitly asks about next steps
+- When the user selects option A/B/C at an approval gate and you need to confirm what follows
+
+---
+
+## Input Expectations
+
+This skill fires automatically — it does not require explicit user input. It reads from the active session context:
+
+| Input | Source | Description |
+|---|---|---|
+| `current_phase` | `project_state.md` or context | Lifecycle phase just completed or currently active |
+| `current_domain` | Detected or stated in session | Domain key (software, content, research, etc.) |
+| `last_artifact` | Just produced in this response | The deliverable, approved increment, or answered question |
+| `open_decisions` | `project_state.md` | Any unresolved questions or deferred choices |
+| `project_constraints` | `project.yaml` or stated constraints | Hard limits that options must not violate |
+
+**If context is missing:**
+- `current_phase` — if unclear (e.g., session just started), surface 3 clarifying questions instead of next-step options.
+- `last_artifact` — if no artifact was just produced, use the most recent approved item from the conversation.
+- `open_decisions` — if none recorded, infer likely next steps from the current phase alone.
+- `project_constraints` — if none known, options may be generic; note this and suggest running `init_project.py` to load project context.
+
+---
+
+## Output Format
+
+Append this block at the end of the response, after the main artifact or answer:
+
+```
+---
+**What to do next** (pick one):
+
+**[Recommended] A: <specific, action-verb name>**
+Why: <one sentence — must connect to the project's current state, known constraint, or open risk>
+Effort: <~N mins | ~N hours | ~1 session | ~N sessions>
+Token cost: <low | medium | high>
+Command: `python agents-maker/tools/generate_prompt.py "<A description verbatim>"`
+
+**B: <specific, action-verb name>**
+Why: <one sentence>
+Effort: <estimate> | Token cost: <low | medium | high>
+
+**C: <specific, action-verb name>**
+Why: <one sentence>
+Effort: <estimate> | Token cost: <low | medium | high>
+
+_Not what you need? Describe your actual next step and the Orchestrator will re-plan._
+---
+```
+
+---
+
+## Token Cost Key
+
+| Level | Meaning |
+|---|---|
+| low | Conversation only — no files needed; very short context |
+| medium | 3–5 source files needed; normal session size |
+| high | Full repo scan or large diff needed; use `project_summary.py` first |
+
+---
+
+## Ranking Rules
+
+**Option A — Recommended** must be:
+- The highest-impact move given the current phase and project state
+- The lowest-risk choice (reversible, testable, doesn't lock future decisions)
+- Directly executable in the next session
+
+**Option B** — A valid alternative with a different priority axis (e.g., speed vs. quality,
+breadth vs. depth, technical vs. documentation).
+
+**Option C** — A "don't ignore this later" option: something with lower immediate urgency but
+higher future cost if deferred (e.g., a growing tech debt item, an untested path, a doc gap).
+
+---
+
+## Rules
+
+- Never suggest an option that contradicts an already-approved artifact or ADR.
+- Options must be specific to this project — not generic advice.
+- If the current phase is unclear (e.g., session just started), surface 3 clarifying questions
+  instead of next-step options.
+- The `Command:` field on Option A always uses the exact phrasing a user can copy-paste.
+- If the project has `key_constraints` in `project.yaml`, check each option against them.
+- Never repeat an option that was just completed in this session.

package/skills/summarize_history.md

@@ -0,0 +1,89 @@
+# Skill: summarize_history
+
+## Description
+
+Compress a multi-turn conversation history into a structured state block that preserves everything critical (requirements, decisions, constraints, open questions) while discarding redundant exchanges, repeated context, and resolved sub-questions. Used by the Compression Agent to reduce context size before sending to any specialist.
+
+---
+
+## When to invoke
+
+- Conversation history exceeds `history_summarize_after_turns` from the active token policy.
+- Total context token count exceeds `max_input_tokens` × 0.75.
+- The user requests "summarize our session so far" or "reset context but keep decisions."
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `history` | Yes | Full conversation history (list of turns) |
+| `active_query` | Yes | The user's current or next question — determines what is most relevant to keep |
+| `never_drop` | No | Explicit list of items the user marked as critical |
+
+**If required input is missing:**
+- `history` — this skill cannot proceed without conversation history. If no history is available, return: "No history to compress — this appears to be a fresh session. Proceed with the active query directly." Do not fabricate history.
+- `active_query` — infer from the most recent user message in the history; note the inference explicitly in the output.
+- `never_drop` — proceed without; apply the standard "What must never be dropped" rules defined below.
+
+---
+
+## Output format
+
+The skill produces a **Conversation State** block:
+
+```
+## Conversation State
+
+**Session goal**: <one sentence: what the user is trying to accomplish overall>
+
+**Completed subtasks**:
+- <subtask> → <outcome>
+- <subtask> → <outcome>
+
+**Active constraints**:
+- Language: <e.g., Python 3.11, no new dependencies>
+- Must not change: <API surface, DB schema, etc.>
+- Must reuse: <existing utilities, patterns>
+- Other: <any hard constraint stated by the user>
+
+**Key decisions made**:
+- <decision> (turn N)
+- <decision> (turn N)
+
+**Open questions**:
+- <question> — <who needs to answer: user | architect | code | unresolved>
+
+**Last action**: <what was produced or agreed in the most recent turn>
+
+**Next action**: <what the user or agent was about to do>
+```
+
+---
+
+## What must never be dropped
+
+Regardless of age or apparent redundancy:
+
+- Any requirement prefixed with "must", "never", "always", "required", "constraint".
+- Any confirmed architectural decision.
+- Any security finding flagged `[SECURITY]`.
+- Any item the user marked "remember this" or "keep this in mind."
+- The user's most recent message (always retained verbatim in the context block).
+
+---
+
+## Token cost tier
+
+**Low.** The skill itself is lightweight. Input (history) can be large; output (state block) is always compact: 150–350 tokens.
+
+Compression hint: this skill is the primary mechanism for token reduction. Invoke it before other compression steps — it usually provides the largest reduction.
+
+---
+
+## Notes
+
+- The state block is a **lossy** compression. Make the loss explicit: always include a "Not captured" line if anything material was omitted for brevity.
+- Do not fabricate decisions. If a decision was discussed but not confirmed, list it under "Open questions" as "Under discussion: <topic>."
+- Turn references (e.g., "turn N") help the user verify accuracy without replaying the full history. Include them for key decisions.

package/skills/write_process_map.md

@@ -0,0 +1,105 @@
+# Skill: write_process_map
+
+## Description
+
+Document a business or operational process as a structured, executable artifact: numbered step table, RACI matrix, and exception-handling table. Used by the Execution Agent in `ops_process` tasks (Phase 3) and the Architect Agent when designing workflows for any domain.
+
+---
+
+## When to invoke
+
+- User requests an SOP, runbook, procedure, workflow, or process documentation.
+- Architect Agent needs to specify an operational process as part of a solution design.
+- Review phase identifies a process that lacks owner assignments or exception paths.
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `process_name` | Yes | Name of the process (e.g., "Incident Response", "Customer Onboarding") |
+| `actors` | Yes | List of roles involved (e.g., `["On-call Engineer", "Team Lead", "Customer"]`) |
+| `trigger` | Yes | What initiates this process (e.g., alert fired, form submitted, scheduled) |
+| `steps` | Yes | Ordered list of steps. Each step: `{action, actor, tool_or_system, output}` |
+| `exception_paths` | No | List of known failure conditions and their recovery steps |
+| `goal` | No | One-sentence description of the successful outcome |
+| `sla` | No | Time constraints (e.g., "acknowledge within 15 min, resolve within 4h") |
+
+**If required input is missing:**
+- `process_name` — ask: "What is this process called? (e.g., 'Weekly Deploy', 'Customer Escalation')"
+- `actors` — ask: "Who are the roles involved? List each as a job title or system name."
+- `trigger` — ask: "What starts this process? (e.g., an alert, a request, a scheduled event)"
+- `steps` — ask: "Walk me through the steps. For each, tell me: who does what, using which tool, and what is the output?"
+- `exception_paths` — default to "None documented" and note the gap in the output.
+
+---
+
+## Output format
+
+### 1. Process Overview
+
+```
+## Process: <process_name>
+**Trigger**: <trigger>
+**Goal**: <goal or "not specified">
+**SLA**: <sla or "not specified">
+**Actors**: <comma-separated list>
+```
+
+### 2. Step Table
+
+```markdown
+## Process Steps
+
+| # | Step | Actor | Tool / System | Output |
+|---|---|---|---|---|
+| 1 | <action> | <actor> | <tool> | <output> |
+| 2 | ... | ... | ... | ... |
+```
+
+### 3. RACI Matrix
+
+```markdown
+## RACI Matrix
+
+| Step | <Actor 1> | <Actor 2> | <Actor N> |
+|---|---|---|---|
+| 1 — <step name> | R | A | I |
+| 2 — <step name> | C | R | — |
+
+Legend: R = Responsible, A = Accountable, C = Consulted, I = Informed, — = Not involved
+```
+
+Each step must have exactly one **A** (Accountable). If no accountable role is clear, flag it: `[A: unassigned — confirm ownership]`.
+
+### 4. Exception-Handling Table
+
+```markdown
+## Exception Paths
+
+| Condition | Detected at step | Recovery action | Owner |
+|---|---|---|---|
+| <failure condition> | <step #> | <what to do> | <role> |
+```
+
+If no exception paths were provided, output:
+```
+## Exception Paths
+No exception paths documented. Recommended: add paths for the 2–3 most likely failure conditions.
+```
+
+---
+
+## Token cost tier
+
+**Low.** Pure document generation from structured inputs. Typical output: 200–500 tokens.
+
+---
+
+## Notes
+
+- Validate that every step has an actor. If a step has no actor, flag it: `[Actor: unassigned]`.
+- RACI matrix rows correspond 1:1 to the steps in the step table.
+- If `actors` contains systems (not people), assign them R only, never A.
+- For processes with more than 20 steps, suggest splitting into sub-processes at natural phase boundaries.

package/skills/write_tests.md

@@ -0,0 +1,97 @@
+# Skill: write_tests
+
+## Description
+
+Generate unit and integration test stubs for a given function, class, or endpoint. Tests follow the project's existing fixture patterns, assertion style, and test framework. Output is ready-to-run test code with one-line explanations per test case.
+
+---
+
+## When to invoke
+
+- The Code Agent is asked to add or improve test coverage.
+- A new function or endpoint has been implemented and needs tests.
+- A bug fix needs a regression test to prevent recurrence.
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `target_code` | Yes | The function, class, or endpoint to test |
+| `test_type` | Yes | `unit` \| `integration` \| `both` |
+| `existing_tests` | No | A representative existing test file to extract fixture and assertion patterns |
+| `test_framework` | No | `pytest` \| `unittest` \| `jest` \| `vitest` \| `go test` \| other (inferred from existing_tests) |
+| `fixtures_available` | No | List of fixture names available in the project |
+| `coverage_targets` | No | Specific paths/branches to target (default: happy path + top 3 error cases) |
+
+**If required input is missing:**
+- `target_code` absent → ask: "Please paste the function, class, or endpoint you want tests for."
+- `test_type` absent → default to `unit`; state this assumption in the output header.
+- `existing_tests` absent and `test_framework` absent → infer framework from the project stack in `project.yaml` (e.g., Python → pytest, JS → jest). State the inferred framework explicitly. If stack is unknown, default to pytest and note it.
+
+---
+
+## Output format
+
+```python
+# tests/test_<module>.py
+
+import pytest
+# (other imports matching project conventions)
+
+# --- Fixtures (only if new fixtures are needed) ---
+
+@pytest.fixture
+def <fixture_name>():
+    # <one-line: what this fixture provides>
+    ...
+
+
+# --- Test cases ---
+
+def test_<function>_<scenario>():
+    # Happy path: <what is being verified>
+    ...
+
+def test_<function>_<error_scenario>():
+    # Error case: <what condition triggers this>
+    ...
+
+def test_<function>_<edge_case>():
+    # Edge case: <what boundary is being tested>
+    ...
+```
+
+After the code block, append a coverage summary:
+
+```
+## Coverage Summary
+
+| Test case | Type | What it verifies |
+|---|---|---|
+| `test_create_user_success` | unit | Returns 201 and user ID on valid input |
+| `test_create_user_duplicate_email` | unit | Returns 409 when email already exists |
+| `test_create_user_invalid_payload` | unit | Returns 400 with field-level errors |
+
+## Not covered (out of scope or requires additional fixtures)
+- Database rollback behavior on concurrent inserts
+- Token expiry edge case (requires time-mocking fixture)
+```
+
+---
+
+## Token cost tier
+
+**Medium.** Scales with number of test cases. Typical output: 300–600 tokens per function under test.
+
+Compression hint: request `test_type: unit` and `coverage_targets: happy_path_only` for a minimal first pass. Integration tests can be added in a follow-up turn.
+
+---
+
+## Notes
+
+- **Never use `time.sleep()` in tests.** If time-dependent behavior must be tested, note it in "Not covered" and suggest the appropriate mocking approach.
+- **Do not generate tests for third-party libraries** — test only the project's own logic.
+- **Match existing patterns exactly**: if the project uses `assert response.status_code == 200` (not `assertEqual`), follow that style throughout.
+- **Regression tests**: if invoked after a bug fix, prefix the test name with `test_regression_` and include a comment: `# Regression: <short description of the bug>`.