@sous-io/sous 0.1.1 → 0.2.1

package/shared-prompts/skills/control-flow/opine/SKILL.tpl.md

@@ -1,58 +0,0 @@
----
-name: opine
-description: >
-  Used to send an idea or proposal to the agent and have it repeat it back, then offer an honest
-  analysis of viability, practicality, and overall merit. This is a discussion; no action is taken.
-argument-hint: idea or proposal
-disable-model-invocation: true
----
-
-New Idea/Proposal:
-$ARGUMENTS
-
--
-
-## CRITICAL: DO NOT ACT ON THIS IDEA
-
-This is a discussion, not a request. You must NOT take any action: do not write code, do not edit
-files, do not create branches, do not modify anything. The user is thinking out loud and wants
-your opinion. Your only output is text directed at the user.
-
-## Research
-
-You may research the codebase and/or the web before responding if you think it would improve the
-accuracy of your analysis. Most ideas won't need this; use your judgement. When you do research,
-prefer sub-agents and run them in parallel where practical.
-
-## Step 1: Repeat
-
-Repeat the idea or proposal back to me, in your own words and in a well-structured format so
-that I know our understandings are aligned.
-
-## Step 2: Analyze
-
-After repeating the idea back, offer your analysis in three parts:
-
-1. **Viability**: Is this idea technically feasible? Are there any fundamental blockers or
-   constraints that would prevent it from working?
-
-2. **Practicality**: Even if viable, is it practical? Would it require more steps, complexity,
-   or hacky code than I'm probably anticipating? Are there hidden costs (maintenance burden,
-   performance implications, edge cases)?
-
-3. **Opinion**: Is this a good idea? Give your honest take on whether this is the right approach.
-
-## Guidelines
-
-- **No action.** This cannot be overstated. Do not act on the idea. Only discuss it.
-- Be open and honest. Push back when you genuinely see problems.
-- "Yes, that seems like a great idea" is an entirely valid response. Do not manufacture
-  objections or play devil's advocate just for the sake of it. If the idea is sound, say so.
-  If it has real problems, say that too.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
-template and the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/repeat/SKILL.tpl.md

@@ -1,27 +0,0 @@
----
-name: repeat
-description: >
-  Used to send an instruction to the agent and have the agent repeat the instruction back to you
-  before acting, to ensure that you and the agent are aligned.
-argument-hint: instruction
-disable-model-invocation: true
----
-
-New Instruction:
-$ARGUMENTS
-
--
-
-DO NOT ACT, yet. Instead, I want you to repeat the instruction back to me, in your own words and
-in a well-structured format so that I know our understandings are aligned. If I am satisfied with
-your explanation, I will approve you to begin acting.
-
-You may do a small amount of research before repeating the instruction back to me, if you think
-it would allow you to be more precise or accurate in your explanation.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
-template and the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/research/SKILL.tpl.md

@@ -1,34 +0,0 @@
----
-name: research
-description: Run a research task using background sub-agents
-user-invocable-only: true
-arguments-hint: what to research via background subagents
----
-
-Have a background sub-agent do the following:
-$ARGUMENTS
-
-## Prefer Parallelism
-
-If possible, practical, and reasonable, break the task into multiple parts and assign each part to a sub-agent.
-Running background sub-agents in parallel usually makes things go much faster. Don't break tiny tasks up, though.
-
-Batch the independent dispatches into one message so they run at once. Opus by default; Sonnet only
-for rote extraction.
-
-## Sub-Agent Prompts
-
-Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), each prompt
-must be self-contained: the question to answer, the
-paths/IDs/facts needed, which skills to load, and the shape of the answer wanted. Sub-agents start
-fresh and cannot see this conversation.
-
-Each returns a concise summary, not a file dump. Do not fabricate or predict a pending result; wait
-for the notification. Synthesis and reporting to the user are orchestrator-only.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
-template and the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/sous-skills/about-sous/SKILL.tpl.md

@@ -1,51 +0,0 @@
----
-name: about-sous
-description: >
-  YOU MUST load this skill when you cannot edit a file in this project, are asked why
-  a file keeps reverting, need to know where the source of truth for any managed file
-  lives, or need to understand what this project's configuration system is.
-user-invocable: false
----
-
-# About Sous
-
-Sous (`xcv`) is a CLI tool that compiles markdown templates and manages output files
-for AI coding agents. It reads a central configuration, resolves variables, and
-copies or renders files to their destinations in this project.
-
-## Files You Must Never Edit
-
-Sous manages certain files in this project by compiling them from a central source.
-**You must never edit these directly.** Your changes will be silently overwritten the
-next time Sous runs:
-
-- `.claude/` — Claude Code configuration, skills, and instructions
-- `.codex/` — Codex configuration and skills
-- `AGENTS.md` and `CLAUDE.md` — agent instruction files
-- Any file you did not create yourself in a designated source directory
-
-If you need to change something in one of these files, the change must be made at the
-source — in the central configuration this project uses with Sous.
-
-## Where Your Skills Live
-
-Skills for this project live at `{{ skillsRoot }}`. That is the source directory Sous
-compiles from. Create and edit skills there — never in `.claude/skills/` or
-`.codex/skills/` directly.
-
-YOU MUST load `create-skill` when creating a new skill for this project.
-
-## Sous's Shared Skill Bundles
-
-Sous ships shared skill bundles at `{{ sousRootPath }}/shared-prompts/skills/`, which is
-where the `about-sous`, `about-agent-skills` and `about-liquid-templates` skills you are
-reading came from. Edit them only in the sous repository itself, where they are the
-sources. Never edit a compiled copy of them inside a consuming project — that copy is
-build output and is overwritten on the next Sous run.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/about-task-files/SKILL.tpl.md

@@ -1,122 +0,0 @@
----
-name: about-task-files
-description: YOU MUST load this skill when working with task files — including creating, reading, updating, or archiving a task file, or any time you need to know where task files live.
-user-invocable: false
----
-
-A **task file** is a Markdown document that tracks a unit of work across one or more chat sessions. It is the single source of truth for what has been done, what remains, and what decisions were made.
-
-## Who Reads and Writes It
-
-Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), reading and
-writing task files is delegated work: the orchestrator supplies the facts and decisions, and a
-sub-agent loads this skill and does the edit.
-Sub-agents start with fresh context and cannot see the chat conversation, so a delegating prompt
-must state any fact that exists only in the conversation. Anything the sub-agent can gather itself
-(branch name, commits, changed files, error output) should be gathered by the sub-agent.
-
-## Location and Naming
-
-Task files live at:
-```
-{{ taskFileRoot }}/[branch-name].md
-```
-
-The filename mirrors the full git branch name — including any `/` separators as path separators:
-- Branch `{{ featureBranchPrefix }}{{ ticketIdExample }}-some-feature` → `{{ taskFileRoot }}/{{ featureBranchPrefix }}{{ ticketIdExample }}-some-feature.md`
-
-To find the current task file: run `git status`, take the branch name, construct the path above.
-
-**If the file is not found:** run a fresh `git status` to confirm the branch name before concluding it doesn't exist.
-
-## Archive Location
-
-Completed task files are archived at:
-```
-{{ taskFileRoot }}/archive/[branch-name].md
-```
-
-The path structure mirrors the task file location — just under `archive/`.
-
-## Completion Procedure
-
-When the user confirms a task is 100% complete:
-1. Update the task file with the final status
-2. Move it to `{{ taskFileRoot }}/archive/[branch-name].md` (create subdirectories as needed)
-3. Switch to the project's main development branch and follow its branch-switching procedures
-
-## File Format
-
-```markdown
-# Task: [Feature/Fix Description]
-
-**Branch:** `{{ featureBranchPrefix }}{{ ticketIdExample }}-feature-name`
-**Status:** In Progress - Phase 2 Complete
-**Started:** YYYY-MM-DD
-**Updated:** YYYY-MM-DD
-
-## Overview
-[Brief description of the task objective]
-
-## Current Status
-- Phase 1: Complete
-- Phase 2: Complete
-- Phase 3: In Progress
-
-## Recent Progress
-[What was accomplished in the most recent session]
-
-## Decisions Made
-[Technical and process decisions, with brief rationale]
-
-## Remaining Work
-- [ ] Task with context
-- [ ] Another task
-
-## Pending Issues
-[Unresolved problems, blockers, open questions]
-
-## Key Learnings
-[Patterns, discoveries, gotchas worth remembering]
-
-## Commits Made
-- `abc123f` - description
-
-## Files Modified
-- /absolute/path/to/File.ts:45 - what changed and why
-
-## Testing URLs
-- http://localhost:5173/path/to/page
-
-## Unresolved Errors
-[Test failures, build errors, TypeScript errors — with paths and line numbers]
-```
-
-## Style Guidelines
-
-- No emojis or emoticons
-- Concise but not aggressively compressed — important information must not be lost
-- Wrap long lines at 120 characters
-- Absolute paths with line numbers for file references (not ranges)
-- Use `file:/absolute/path/to/File.ts:45` format for clickable links (two slashes, not three)
-
-## File Size
-
-Task files must not exceed **1,000 lines**. When approaching the limit, condense:
-- Completed phases (keep summary, drop detail)
-- Historical context no longer relevant to upcoming work
-- Information less important to immediate next steps
-
-Always preserve in full: current active work, immediate next steps, unresolved issues, recent learnings, recently modified files.
-
-## Task Plan Structure
-
-When drafting a task plan, segregate work by architectural layer. Work one layer at a time and
-commit at least once per layer.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/continue-task-in-new-branch/SKILL.tpl.md

@@ -1,80 +0,0 @@
----
-name: continue-task-in-new-branch
-description: YOU MUST load this skill when an MR has been merged and remaining work needs to continue in a new branch — including "continue this work in a new branch", "create a follow-up branch", "split this into another MR", "move remaining work to a new branch".
----
-
-The agent performing this work MUST load `about-task-files`.
-
-## Delegation
-
-Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), the
-orchestrator does the git branch work itself (steps 1, 2,
-and 6, which change the working tree it is in) and delegates the task file writing (steps 3, 4, 5)
-to one Opus sub-agent. That sub-agent needs the old and new branch names, the remaining-work list,
-and the patterns/gotchas to carry forward; sub-agents cannot see this conversation, so state them in
-the prompt.
-
-## Steps
-
-### 1. Prepare for Branch Transition
-
-Before switching branches, ensure:
-- Current branch is fully pushed to the remote
-- All important context is documented in the current task file (load `update-task-file` if needed)
-- The MR has been merged or is ready to close
-
-### 2. Create the New Branch
-
-Name the new branch using the original name plus a letter suffix (`-b`, `-c`, etc.):
-```bash
-git checkout <main-development-branch>
-git pull origin <main-development-branch>
-git checkout -b {{ featureBranchPrefix }}{{ ticketIdExample }}-description-b
-```
-
-### 3. Create the New Task File
-
-Create `{{ taskFileRoot }}/{{ featureBranchPrefix }}{{ ticketIdExample }}-description-b.md` with:
-- **Task Overview**: brief description and connection to the previous MR
-- **Remaining Work**: clear list of unfinished tasks with enough context to understand each item independently
-- **Key Patterns and Learnings**: essential patterns from the previous branch worth carrying forward
-- **Important Notes**: critical gotchas, blockers, or dependencies
-
-Do NOT include: completed tasks (unless essential context), resolved MR comments, detailed change history.
-
-### 4. Update the Old Task File
-
-Add a "Work Continuation" section to the old task file before archiving:
-
-```markdown
-## Work Continuation
-Remaining work has been moved to:
-- **Branch**: {{ featureBranchPrefix }}{{ ticketIdExample }}-description-b
-- **Task File**: {{ taskFileRoot }}/{{ featureBranchPrefix }}{{ ticketIdExample }}-description-b.md
-- **Scope**: [brief description of remaining work]
-
-This task file is now archived — work in the associated MR has been completed and merged.
-```
-
-### 5. Archive the Old Task File
-
-```bash
-mv {{ taskFileRoot }}/{{ featureBranchPrefix }}{{ ticketIdExample }}-description-a.md \
-   {{ taskFileRoot }}/archive/{{ featureBranchPrefix }}{{ ticketIdExample }}-description-a.md
-```
-
-Create the archive subdirectory if it doesn't exist.
-
-### 6. Clean Up
-
-```bash
-# Delete the old local branch
-git branch -D {{ featureBranchPrefix }}{{ ticketIdExample }}-description-a
-```
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/go/SKILL.tpl.md

@@ -1,14 +0,0 @@
----
-name: go
-description: Resume work on the current branch task — load the task file, analyze progress, identify next steps, and present options.
-disable-model-invocation: true
----
-
-@~sous-shared/_partials/resume-task.md
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/resume-task/SKILL.tpl.md

@@ -1,13 +0,0 @@
----
-name: resume-task
-description: YOU MUST load this skill when the user is resuming work on an existing task — including "resume work", "continue from where we left off", "what's the status?", "what should we do next?", "read the task file", or when starting a new session on a branch that has an existing task file.
----
-
-@~sous-shared/_partials/resume-task.md
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/start-task/SKILL.tpl.md

@@ -1,93 +0,0 @@
----
-name: start-task
-description: >
-  YOU MUST load this skill when the user wants to start work on a new task — including "start a
-  new task", "let's work on {{ ticketIdExample }}", "begin a new task", "create a task file", or
-  any request to begin fresh work on a ticket.
----
-
-The agent performing this work MUST load `about-task-files` and any "about" skills related to the
-project's task management system (e.g. Jira, Linear, etc.).
-
-## Delegation
-
-Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`):
-
-- **Orchestrator-only:** every step that needs the user (picking the ticket, confirming the branch
-  name, approving the plan) and the git branch operations, which change the working tree the
-  orchestrator is in.
-- **Delegated:** pulling ticket info (step 2) and writing the task file (step 4), each to a
-  background sub-agent. Dispatch them in parallel when independent.
-- Sub-agents return links, questions, and confirmations to the orchestrator, which relays them to
-  the user.
-
-## Steps
-
-### 1. Identify the Ticket
-
-Look for a ticket identifier (e.g. `{{ ticketIdExample }}`) in the user's message. If none is
-provided:
-- Ask the user to specify one, or offer to help them pick one
-- Once a ticket number is confirmed, proceed
-
-### 2. Pull Ticket Info
-
-Delegate to a sub-agent: fetch basic ticket info from the project's task management system and
-report it back. If the ticket doesn't exist, go back to step 1. If unassigned, ask the user if they
-want to assign it to themselves. If the status indicates it hasn't been started, ask if they want to
-transition it to an active state. Those questions are orchestrator-only; the sub-agent reports the
-assignee and status and the orchestrator asks.
-
-After transitioning, ensure the issue is visible on the team's board. If the project ships an
-"about" skill for its task management system (e.g. `about-jira`, `about-linear`), follow its
-board-move instructions for the board type and target status.
-
-### 3. Check for an Existing Branch
-
-Look for local branches that include the ticket number:
-```bash
-git branch | grep {{ ticketIdExample }}
-```
-
-If found, confirm it's the right branch with the user (there may be multiple), then:
-```bash
-git checkout [branch-name]
-git pull origin [branch-name]
-```
-Then go to step 4.
-
-### 3a. Create a New Branch
-
-If no existing branch is found:
-
-1. Switch to the project's main development branch and pull latest
-2. Resolve branch name: `{{ featureBranchPrefix }}{{ ticketPrefix }}[ticket-number]-[short-description]`
-   derived from the ticket title. **Confirm with the user before creating.**
-3. Create and switch to the branch:
-   ```bash
-   git checkout -b [branch-name]
-   ```
-
-### 4. Load or Create the Task File
-
-Check for an existing task file at `{{ taskFileRoot }}/[branch-name].md`.
-
-- **Found**: read it, note what's already captured, and continue to step 5
-- **Not found**: delegate to a sub-agent, which collects full ticket info (summary, description,
-  status, assignee, related issues, comments, story points, sub-tasks, any linked MRs or commits)
-  and creates the task file using the format in `about-task-files`. Include relevant testing URLs
-  with real record IDs so URLs are actually clickable. Use `file:/absolute/path:line` format for
-  source file links.
-
-### 5. Plan and Start
-
-The orchestrator drafts the task plan, organized by layer (see `about-task-files` for layer
-ordering), and asks the user if they want to begin work. Recording the approved plan in the task
-file is delegated; pass the plan text to the sub-agent verbatim.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
-template and the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/update/SKILL.tpl.md

@@ -1,14 +0,0 @@
----
-name: update
-description: Update the task file before ending the session or when context is running low.
-disable-model-invocation: true
----
-
-@~sous-shared/_partials/update-task-file.md
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/task-files/update-task-file/SKILL.tpl.md

@@ -1,13 +0,0 @@
----
-name: update-task-file
-description: YOU MUST load this skill when context is running low, the user is ending the session, or they say "update the task file", "document our progress", "save our state", "prepare for new session", or invoke the !update command.
----
-
-@~sous-shared/_partials/update-task-file.md
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}