feat: enterprise FE patterns, project-tooling-discovery, explore commands, and team workflows

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sys",
   "description": "Production-grade engineering skills created by Systango Technologies for AI coding agents — covering the full software development lifecycle from spec to ship.",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "author": {
     "name": "Systango Technologies"
   },

.claude/commands/discover.md

@@ -31,3 +31,7 @@ Using discovered facts, create or update `CLAUDE.md` at project root with Tech S
 **Step 5: Verify (Mandatory)**
 
 Pick 3 specific claims from `.context/` files and verify them against actual code (e.g., check package.json matches stack.md, find a test file to verify conventions.md, read one route handler to verify architecture.md). Fix any incorrect claims before proceeding.
+
+**Mode: Targeted Reference Trace**
+
+If the task is finding all usages of a specific symbol, flag, or string (not broad mapping), skip the full discovery and run the **Targeted Reference Trace** workflow from the skill instead. Use exact search (`rg`/`grep`) first, classify results into definition/usage/test/config, and output a reference table.

.claude/commands/review.md

@@ -4,6 +4,8 @@ description: Conduct a five-axis code review — correctness, readability, archi
 
 Invoke the sys:code-review-and-quality skill.
 
+Start from the full changeset diff (`git diff` or merge-base diff), not file-by-file. Write an executive summary of scope and risk areas first, then deep-dive only where needed.
+
 Review the current changes (staged or recent commits) across all five axes:
 
 1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate?
@@ -12,5 +14,5 @@ Review the current changes (staged or recent commits) across all five axes:
 4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill)
 5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill)
 
-Categorize findings as Critical, Important, or Suggestion.
+Categorize findings as **Critical** (blocks merge), **Important** (should address), or **Suggestion** (optional).
 Output a structured review with specific file:line references and fix recommendations.

.claude/commands/ship.md

@@ -7,6 +7,11 @@ Invoke the sys:shipping-and-launch skill.
 Run through the pre-launch checklist:
 
 1. **Review Gate** — Code reviewed and approved, no TODOs blocking launch, no console.logs
-2. **Documentation** — README current, ADRs written, changelog updated
+2. **Security** — Dependency audit clean, no secrets in code, auth in place, headers configured
+3. **Performance** — Core Web Vitals good, no N+1 queries, images optimized, bundle sized
+4. **Web Quality** — Meta tags complete, Open Graph set, Lighthouse >= 90, CWV within thresholds, accessibility audit clean, sitemap present, error tracking configured
+5. **Accessibility** — Keyboard nav works, screen reader compatible, contrast adequate, axe-core clean
+6. **Infrastructure** — Env vars set, migrations ready, monitoring configured
+7. **Documentation** — README current, ADRs written, changelog updated
 
 Report any failing checks and help resolve them before deployment.

.gitignore

@@ -27,3 +27,6 @@ build/
 
 # Logs
 *.log
+
+# Working documents (proposals, drafts)
+docs/proposal-*.md

AGENTS.md

@@ -22,26 +22,39 @@ OpenCode uses a **skill-driven execution model** powered by the `skill` tool and
 The agent should automatically map user intent to skills:
 
 - Feature / new functionality → `spec-driven-development`, then `incremental-implementation`
+- Small task / bug fix / UI tweak / config change → `quick-task-execution`
 - Planning / breakdown → `planning-and-task-breakdown`
 - Bug / failure / unexpected behavior → `debugging-and-error-recovery`
 - Code review → `code-review-and-quality`
 - Refactoring / simplification → `code-simplification`
 - API or interface design → `api-and-interface-design`
 - UI work → `frontend-ui-engineering`
 - PM-first PRD/epic/work-item planning → `syspm` (mirrored workflow), with `pm-spec-and-prd`, `pm-epic-decomposition`, and `pm-jira-sync` available as split variants
+- Idea refinement / brainstorming a concept → `idea-refine`
+- Writing / generating tests → `generate-unit-tests`
+- Browser / E2E / visual testing → `browser-testing-with-devtools`
+- Documentation / ADRs / READMEs → `documentation-and-adrs`
+- Deprecation / migration / version upgrades → `deprecation-and-migration`
+- Git workflow / branching / versioning → `git-workflow-and-versioning`
+- Verifying against official docs / sources → `source-driven-development`
+- Pre-launch / deployment readiness → `shipping-and-launch`
 
 ### Lifecycle Mapping (Implicit Commands)
 
 OpenCode does not support slash commands like `/spec` or `/plan`.
 
 Instead, the agent must internally follow this lifecycle:
 
+- DISCOVER → `brownfield-discovery`
 - DEFINE → `spec-driven-development`
 - PLAN → `planning-and-task-breakdown`
 - SYNC JIRA BOARD (when using Jira specs/plans) → `jira-board-sync` after refined `jira-spec/{story-id}/` artifacts exist
 - BUILD → `incremental-implementation`
 - VERIFY → `debugging-and-error-recovery`
 - REVIEW → `code-review-and-quality`
+- SHIP → `shipping-and-launch`
+- EXPLORE → `idea-refine` (refine raw ideas into actionable concepts with frameworks)
+- QUICK → `quick-task-execution` (small tasks — prefer this for bug fixes, UI tweaks, config changes)
 
 For PM-first SysPM workflows, use:
 
@@ -65,7 +78,7 @@ The following thoughts are incorrect and must be ignored:
 
 - "This is too small for a skill"
 - "I can just quickly implement this"
-- "I’ll gather context first"
+- "I'll gather context first"
 
 Correct behavior:
 
@@ -177,4 +190,4 @@ cp -r skills/{skill-name} ~/.claude/skills/
 **claude.ai:**
 Add the skill to project knowledge or paste SKILL.md contents into the conversation.
 
-If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
+If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.

CLAUDE.md

@@ -16,15 +16,18 @@ docs/         → Setup guides for different tools
 ## Skills by Phase
 
 **Discover:** brownfield-discovery
-**Define:** spec-driven-development, jira-spec-driven-development
-**Plan:** planning-and-task-breakdown, jira-planning-and-task-breakdown  
+**Define:** spec-driven-development, jira-spec-driven-development, source-driven-development
+**Plan:** planning-and-task-breakdown, jira-planning-and-task-breakdown
 **Sync Jira (after plan):** jira-board-sync
 **SysPM (PM workflow):** syspm, pm-spec-and-prd, pm-epic-decomposition, pm-jira-sync, pm-status-and-reporting
-**Build:** incremental-implementation, context-engineering, frontend-ui-engineering, api-and-interface-design  
-**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
+**Build:** incremental-implementation, context-engineering, frontend-ui-engineering, api-and-interface-design
+**Verify:** generate-unit-tests, browser-testing-with-devtools, debugging-and-error-recovery
 **Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
 **Ship:** documentation-and-adrs, shipping-and-launch, jira-shipping-and-launch
 **Ad-hoc:** quick-task-execution
+**Explore:** idea-refine
+
+**Maintain:** deprecation-and-migration, git-workflow-and-versioning
 
 ## Conventions
 
@@ -53,4 +56,3 @@ All skills are invoked via slash commands with the `sys:` prefix (e.g., `/discov
 - Always: Follow the skill-anatomy.md format for new skills
 - Never: Add skills that are vague advice instead of actionable processes
 - Never: Duplicate content between skills — reference other skills instead
-

docs/team-rollout.md

@@ -0,0 +1,96 @@
+# Team Rollout Guide
+
+How to adopt `agent-skills` across a development team. This guide covers installation, prerequisites, and best practices for getting consistent results from AI coding agents.
+
+## Prerequisites
+
+Before rolling out to the team, ensure:
+
+1. **AI agent tool is configured** — Claude Code, Cursor with Claude, or another supported agent
+2. **Git workflow established** — the team uses branches, PRs, and code review
+3. **Linter and formatter configured** — ESLint, Prettier, or equivalent so agent output matches team style
+4. **CI pipeline exists** — automated build/test/lint on PR (agents verify locally, CI enforces)
+
+## Installation
+
+### Claude Code
+
+```bash
+# Install the plugin from the marketplace
+/plugin install sys@systango-agent-skills
+
+# Or install manually from the repo
+git clone https://github.com/SystangoTechnologies/agent-skills.git
+cp -r agent-skills/skills/ ~/.claude/skills/
+cp -r agent-skills/.claude/commands/ ~/.claude/commands/
+```
+
+### Cursor
+
+Add the skill files to your project's `.cursor/skills/` directory or reference them in workspace rules.
+
+### Other Agents (OpenCode, Copilot, etc.)
+
+Copy `AGENTS.md` into your repository root. The intent-to-skill mapping in that file guides any agent that reads it.
+
+## First-Day Setup for New Team Members
+
+1. **Install the plugin** (see above)
+2. **Run `/discover` on the project** — generates `.context/` files that help all subsequent skills understand the codebase
+3. **Read the Quick Reference** — know which command to use when (see below)
+
+## Quick Reference
+
+| I want to... | Command | Skill |
+|---|---|---|
+| Fix a bug, make a small change | `/quick` | `quick-task-execution` |
+| Understand a new codebase | `/discover` | `brownfield-discovery` |
+| Find all references to a symbol | `/discover` (trace mode) | `brownfield-discovery` |
+| Write a spec for a feature | `/spec` | `spec-driven-development` |
+| Break a feature into tasks | `/plan` | `planning-and-task-breakdown` |
+| Build the feature | `/build` | `incremental-implementation` |
+| Review a PR | `/review` | `code-review-and-quality` |
+| Simplify complex code | `/code-simplify` | `code-simplification` |
+| Prepare for deployment | `/ship` | `shipping-and-launch` |
+
+## Task Size Triage
+
+The most common mistake is using heavyweight workflows for small tasks. Use this decision tree:
+
+| Task Size | Examples | Workflow |
+|---|---|---|
+| **Small** (1-3 files, <100 lines, obvious approach) | Bug fix, UI tweak, config change, rename | `/quick` |
+| **Medium** (3-10 files, clear requirements) | Add a form, new API endpoint, component refactor | `/plan` → `/build` |
+| **Large** (>10 files, ambiguous requirements) | New feature, major refactor, architecture change | `/discover` → `/spec` → `/plan` → `/build` |
+
+**Default to small.** Escalate only when the task genuinely needs ceremony.
+
+## Stack-Specific Notes
+
+### Frontend
+
+The `frontend-ui-engineering` skill covers component architecture, design system adherence, accessibility, error boundaries, and common anti-patterns. It is framework-agnostic — agents read the project's actual dependencies and adapt accordingly.
+
+### Non-JavaScript / Non-Node Projects
+
+All skills use a **project-tooling-discovery** step instead of hardcoded `npm` commands. The agent checks `package.json`, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, and CI workflows to find the right build/test/lint commands. See `references/project-tooling-discovery.md` for details.
+
+## Quality Gates
+
+Before merging any PR, the agent should verify:
+
+1. **Build passes** (project-specific command)
+2. **Tests pass** (project-specific command)
+3. **Lint clean** (project-specific command)
+4. **Type check passes** (project-specific command)
+5. **No TODO comments that should be resolved**
+6. **No debugging statements** (`console.log`, `debugger`)
+7. **For FE launches:** SEO meta tags, Lighthouse >= 90, accessibility audit clean (see `/ship`)
+
+## Tips for Team Leads
+
+1. **Run `/discover` once** after setup and commit the `.context/` directory — it speeds up all subsequent agent interactions for the whole team
+2. **Set up `.cursor/rules/` or `AGENTS.md`** in each repo to guide the agent's behavior with project-specific conventions
+3. **Review agent output early** — the first few PRs from each team member using agents should get extra review to calibrate quality expectations
+4. **Use `/review` on agent-written code** — agents reviewing their own output catches issues that the initial generation missed
+5. **Don't skip `/quick` for small tasks** — the biggest productivity win is using the lightweight path for the 80% of tasks that are small

skills/brownfield-discovery/SKILL.md

@@ -33,6 +33,34 @@ When you land in an unfamiliar codebase, you need to understand *what this thing
 - You already have `.context/` files and they're current (skip directly to the skill using them)
 - The codebase is tiny (one file) — reading it directly is faster
 
+## Targeted Reference Trace
+
+When the task is **finding all usages of a specific symbol, flag, env variable, or string** (not broad codebase mapping), use this focused workflow instead of the full 5-agent discovery:
+
+### Process
+
+1. **Start with exact search.** Use `rg` (ripgrep) or `grep -rn` with the exact string. Filter by relevant paths (`--glob 'apps/**'`, `--glob 'libs/**'`).
+2. **Classify each result.** For every match, categorize it:
+   - **Definition** — where the symbol is declared or created
+   - **Usage** — where it's consumed or called
+   - **Test** — test files referencing it
+   - **Config** — environment files, feature flag configs, CI pipelines
+3. **Follow the dependency chain.** From the definition site, trace imports to find all consumers. From consumers, check for indirect usages (re-exports, wrappers).
+4. **Output a reference table:**
+
+| File:Line | Category | One-line Context |
+|-----------|----------|-----------------|
+| `src/config/flags.ts:42` | Definition | `export const ENABLE_CART = process.env.FEATURE_CART === 'true'` |
+| `src/features/cart/CartPage.tsx:8` | Usage | `if (!ENABLE_CART) return <NotFound />` |
+| `tests/cart.test.ts:15` | Test | `beforeEach(() => process.env.FEATURE_CART = 'true')` |
+
+5. **Cross-reference with `.context/` files** (if they exist) to add architectural context — which module owns this code, what concerns exist.
+
+### When to Use Reference Trace vs Full Discovery
+
+- **"Where is X used?"** / **"Find all references to Y"** → Reference Trace
+- **"What does this codebase do?"** / **"I'm new to this project"** → Full Discovery (5 agents)
+
 ## Process
 
 ### Step 1: Decide Scope
@@ -158,6 +186,7 @@ If any claim is wrong, fix it now. Don't commit context docs that hallucinated d
 | "Parallel agents will miss details" | They're not writing a formal spec — they're writing *discoverable pointers to evidence*. Depth comes from agents reading `.context/` when building, not from a 200-page document. |
 | "This is overhead we can't afford" | It's not overhead. It's building the foundation that all subsequent skills depend on. Skip it, and `spec-driven-development`, `planning`, and `code-review` all become slower. |
 | ".context/ files will go stale" | That's fine. They're not gospel — they're starting points. When you find something wrong, fix it. If a file is stale enough to be harmful, re-run this skill. |
+| "I'll just use semantic search to find it" | Semantic search finds *related* code, not *exact* references. For symbols, flags, and specific strings, exact search (`rg`) first, then broaden only if needed. |
 
 ## Red Flags
 

skills/code-review-and-quality/SKILL.md

@@ -61,7 +61,7 @@ Can another engineer (or agent) understand this code without the author explaini
 - Are there any "clever" tricks that should be simplified?
 - **Could this be done in fewer lines?** (1000 lines where 100 suffice is a failure)
 - **Are abstractions earning their complexity?** (Don't generalize until the third use case)
-- Would comments help clarify non-obvious intent? (But don't comment obvious code.)
+- Would comments help clarify non-obvious intent? (But don't comment obvious code.) Flag narration comments (`// set the value`, `// call the function`, `// return the result`) as Suggestion: remove.
 - Are there dead code artifacts: no-op variables (`_unused`), backwards-compat shims, or `// removed` comments?
 
 ### 3. Architecture
@@ -73,6 +73,7 @@ Does the change fit the system's design?
 - Is there code duplication that should be shared?
 - Are dependencies flowing in the right direction (no circular dependencies)?
 - Is the abstraction level appropriate (not over-engineered, not too coupled)?
+- **Simplicity over DRY:** Small duplication is acceptable when a shared abstraction would add conditionals, indirection, or defensive branches that make the code harder to follow. Don't block a merge because two functions share 5 similar lines — block it when duplication causes real maintenance risk. For larger refactors, cite `code-simplification` as a follow-up, not a merge blocker.
 
 ### 4. Security
 
@@ -157,16 +158,23 @@ Tests reveal intent and coverage:
 
 ### Step 3: Review the Implementation
 
-Walk through the code with the five axes in mind:
+Review in two phases — changeset-first, then deep-dive only where needed:
 
-```
-For each file changed:
+**Phase 1: Changeset Pass**
+Start with the full diff (`git diff` or merge-base diff). Read `git diff --stat` for scope. Write an executive summary:
+- What changed and why (match against spec/ticket)
+- Cross-cutting concerns (shared types changed, API contract shifts, migration needed)
+- Risk areas (security-sensitive files, performance-critical paths, public API changes)
+
+**Phase 2: Deep Pass**
+Go file-by-file only where Phase 1 identified risk. For each flagged file, apply the five axes:
 1. Correctness: Does this code do what the test says it should?
 2. Readability: Can I understand this without help?
 3. Architecture: Does this fit the system?
 4. Security: Any vulnerabilities?
 5. Performance: Any bottlenecks?
-```
+
+Skip deep review for trivial changes (import reordering, formatting, comment updates) unless they mask logic changes.
 
 ### Step 4: Categorize Findings
 
@@ -176,8 +184,8 @@ Label every comment with its severity so the author knows what's required vs opt
 |--------|---------|---------------|
 | *(no prefix)* | Required change | Must address before merge |
 | **Critical:** | Blocks merge | Security vulnerability, data loss, broken functionality |
-| **Nit:** | Minor, optional | Author may ignore — formatting, style preferences |
-| **Optional:** / **Consider:** | Suggestion | Worth considering but not required |
+| **Important:** | Should address | Not a blocker but degrades quality if ignored |
+| **Suggestion:** | Minor, optional | Author may ignore — formatting, style preferences, simplification ideas |
 | **FYI** | Informational only | No action needed — context for future reference |
 
 This prevents authors from treating all feedback as mandatory and wasting time on optional suggestions.

skills/context-engineering/SKILL.md

@@ -66,6 +66,8 @@ Create a rules file that persists across sessions. This is the highest-leverage
 - Lint: `npm run lint --fix`
 - Dev: `npm run dev`
 - Type check: `npx tsc --noEmit`   # only when this repo uses TypeScript and defines this step
+Discover actual commands from `package.json`, `Makefile`, CI config, or `.context/stack.md`.
+See `references/project-tooling-discovery.md`.
 
 ## Code Conventions
 - Functional components with hooks (no class components)