trackfw 2.16.0 → 3.1.0

package/src/integrations/assets/skills/tooling.md

@@ -0,0 +1,80 @@
+---
+name: trackfw-tooling-skill
+description: AI agent design, skill composition, MCP configuration and context economy.
+---
+
+## Agent Design Principles
+
+An agent is effective when its scope, tools and constraints are explicit. Vague instructions
+produce vague behaviour:
+- **Lock the role**: every agent declares its role at the top of its system prompt and does
+  not switch roles mid-session without an explicit handoff.
+- **Declare tools explicitly**: list only the tools the agent needs for its role; an agent
+  with write access that only needs to read is a liability.
+- **Explicit memory scope**: use project-scoped memory for context that belongs to the
+  repository; use global memory only for cross-project preferences.
+- **Restrict scope**: an agent must know what it is forbidden to do (create branches, open PRs,
+  modify configuration outside its domain). Prohibitions are as important as permissions.
+
+## Skill Design
+
+Skills extend agents with domain expertise loaded on demand:
+- **Single responsibility**: one skill per role or domain. A skill that covers both backend
+  and frontend is too broad to be useful without loading the entire file.
+- **Stack-agnostic content**: skills contain principles, patterns and vocabulary that define
+  the role. Stack-specific choices (library names, project configuration) belong in the
+  project's CLAUDE.md, not in a shared skill.
+- **Right size**: 40–90 lines is the target. A 5-line skill teaches nothing; a 300-line
+  skill inflates context on every invocation. Prefer principles over tool lists.
+- **Load on demand**: skills are not always loaded. Design them as self-contained documents
+  that provide value when read in isolation, without assuming other skills are present.
+
+## MCP (Model Context Protocol)
+
+MCP enables agents to interact with external tools and services through a standardised protocol:
+- Define tool schemas precisely: name, description, input schema, output schema.
+- Group related tools in a tool set to reduce context size when only a subset is needed.
+- Prefer tool sets over individual tool registrations when the agent needs more than five tools.
+- Validate MCP server responses before acting on them; a malformed response must not
+  silently corrupt state.
+- Document which MCP servers a configuration depends on; an agent that fails silently because
+  a server is unavailable is hard to debug.
+
+## Prompt Engineering
+
+- **Specificity over length**: a short, specific prompt outperforms a long, vague one.
+  Remove filler instructions that repeat the model's defaults.
+- **Reusable prompt files**: extract repeated prompt patterns into versioned, reviewable files.
+  Treat prompts as code: they have bugs, they drift, they need tests.
+- **Context economy**: every token in context is a cost. Load only the context that is
+  relevant to the current task. Unload when done.
+- **Structured output**: when the downstream consumer is code (not a human), request JSON
+  or a defined schema. Freeform prose is hard to parse reliably.
+
+## Validating Recommendations
+
+Before recommending a tool, configuration option, or API:
+1. Check the official documentation for the current version.
+2. Verify that the feature or flag exists in the version the project is using.
+3. Test in a minimal example before including in a recommendation.
+
+A memory that says "feature X exists" is not the same as "feature X exists now." Models have
+knowledge cutoffs; documentation does not. When in doubt, read the source.
+
+## Human-in-the-Loop
+
+Define checkpoints where human review is mandatory:
+- Irreversible operations (production deploys, data deletions, secret rotation).
+- Operations with significant blast radius (schema migrations, dependency upgrades).
+- Decisions that bifurcate the architecture (new service boundary, new data model).
+
+Agents that can proceed without human input should declare that capability explicitly in their
+design. Agents that are uncertain must ask, not guess.
+
+## Observability for AI Systems
+
+- Log prompts, tool calls, token counts and latency for every agent interaction in production.
+- Monitor for response quality drift: a pipeline that produces correct output today may not
+  produce correct output after a model update.
+- Evaluation datasets: maintain a set of representative inputs with expected outputs; run
+  them on every model or prompt change.

package/src/integrations/assets/skills/ux.md

@@ -0,0 +1,70 @@
+---
+name: trackfw-ux-skill
+description: User-centred design, design systems, accessibility and usability validation.
+---
+
+## User-Centred Design
+
+Design starts with understanding users, not with wireframes. Before sketching, establish:
+- **Who** are the users? (personas, JTBD — Jobs to Be Done)
+- **What** are they trying to accomplish? (user journey, task analysis)
+- **Where** does the current experience fail? (pain points, drop-off analysis)
+
+Design Thinking cycle: Empathize → Define → Ideate → Prototype → Test. The cycle is
+iterative; return to earlier phases when testing invalidates assumptions.
+
+## Prototyping
+
+Prototypes are for learning, not for pride. Build the cheapest prototype that can answer the
+design question:
+- **Low-fidelity** (sketch, wireframe): validates information architecture and flow.
+- **High-fidelity** (interactive prototype): validates micro-interactions and visual language.
+- **Discardable prototypes**: isolated from production code; exist to prove a concept, not
+  to ship. Remove them before the production implementation goes to review.
+
+## Accessibility (WCAG 2.2 AA Minimum)
+
+Accessibility is a legal requirement in many jurisdictions and a quality attribute in all:
+- Color contrast ≥ 4.5:1 for body text; ≥ 3:1 for large text and UI components.
+- All interactive elements are keyboard-operable with a visible focus indicator.
+- ARIA landmarks structure the page for assistive technology; do not use ARIA to override
+  broken semantics — fix the semantics first.
+- `prefers-reduced-motion`: disable or reduce animations for users who opt out.
+- Every form field has a programmatically associated label.
+- Test with a real screen reader; automated tools (axe-core) catch ~30–40% of issues.
+
+## Usability Heuristics
+
+Apply Nielsen's 10 heuristics as a review lens, not a checklist:
+- **Visibility of system status**: users always know what is happening.
+- **Match with the real world**: language and concepts match the user's mental model.
+- **User control and freedom**: support undo and clear exit paths.
+- **Consistency**: same words, same icons, same placement across the product.
+- **Error prevention**: design to make errors impossible before handling them gracefully.
+
+## Design Systems
+
+A design system is a product that serves the product team:
+- **Design tokens** (W3C DTCG format): spacing, colour, typography as named variables.
+  Tokens are the contract between design and code.
+- **Atomic Design**: atoms (button, input) → molecules (form field) → organisms (card) →
+  templates → pages. Each level composes from the level below.
+- Document components in isolation with rendered examples, props API and accessibility notes.
+- A component that cannot be demonstrated without application context is too tightly coupled.
+
+## Validation and Metrics
+
+A design is a hypothesis until tested with users:
+- **A/B testing**: one variable, measurable success criterion, sufficient sample size.
+  Do not run experiments without a pre-registered hypothesis.
+- **Usability testing**: five users reveal the majority of critical usability problems.
+  Recruit from the actual target audience, not convenience.
+- **Quantitative signals**: task completion rate, time on task, error rate, NPS/CSAT.
+- **Qualitative signals**: think-aloud sessions, session replays, support ticket themes.
+
+## Responsive and Adaptive Design
+
+- Mobile-first: design and test the constrained layout first; expand to wider viewports.
+- Touch targets ≥ 48 dp (CSS equivalent) for all interactive elements on touch surfaces.
+- Fluid typography with `clamp()` to eliminate breakpoint-driven font size jumps.
+- Content-driven breakpoints, not device-driven; break where the layout breaks.

package/src/integrations/render.js

@@ -80,8 +80,8 @@ function toolsFor(itemId) {
 // identidade configurada. Sem apelido configurado, apenas o display name do
 // agente é mencionado. Espelha internal/integrations/render.go:greetingLine.
 function greetingLine(displayName, nickname) {
-  if (!nickname) return `Você é ${displayName}.`
-  return `Você é ${displayName}. Trate o usuário como ${nickname}.`
+  if (!nickname) return `You are ${displayName}.`
+  return `You are ${displayName}. Address the user as ${nickname}.`
 }
 
 // insertBodyPrefix insere prefix como a nova primeira linha da seção de
@@ -103,6 +103,54 @@ function insertBodyPrefix(source, prefix) {
   return `${head}\n\n${prefix}\n\n${rest}`
 }
 
+// rewriteSignatureLine reescreve a última linha da seção de corpo de um
+// markdown cru (frontmatter + corpo) que casa com o padrão de assinatura
+// `^— <nome>, <título>$` (travessão em-dash U+2014, espaço, nome, vírgula,
+// espaço, título). Apenas o grupo de nome (primeiro) é substituído por
+// displayName; o título (segundo grupo) é preservado byte a byte.
+//
+// Escopo: a função opera somente no corpo (após o fechamento do frontmatter).
+// Uma linha de assinatura dentro do frontmatter nunca é tocada — a detecção
+// de fronteira espelha rewriteFrontmatterFields exatamente.
+//
+// Se nenhuma linha do corpo casar com o padrão, source é retornado inalterado.
+// Se displayName for vazio, source é retornado inalterado. A função nunca
+// inventa uma assinatura que não estava presente.
+//
+// Espelha internal/integrations/render.go:rewriteSignatureLine.
+function rewriteSignatureLine(source, displayName) {
+  if (!displayName) return source
+  const trimmed = String(source).trim()
+
+  // Localiza o início do corpo — espelha a detecção de fronteira de
+  // rewriteFrontmatterFields para que o escopo de ambas as funções coincida.
+  let bodyStart = 0
+  if (trimmed.startsWith('---\n')) {
+    const end = trimmed.indexOf('\n---', 4)
+    if (end >= 0) {
+      bodyStart = end + 4 // aponta para o char imediatamente após "\n---"
+    }
+  }
+  const head = trimmed.slice(0, bodyStart)
+  const bodySection = trimmed.slice(bodyStart)
+
+  const lines = bodySection.split('\n')
+  // Percorre de trás para frente para encontrar a ÚLTIMA linha candidata.
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line.startsWith('— ')) continue
+    const rest = line.slice('— '.length) // pula "— "
+    const commaIdx = rest.indexOf(', ')
+    if (commaIdx < 0) continue
+    const title = rest.slice(commaIdx + 2)
+    if (!title) continue
+    lines[i] = `— ${displayName}, ${title}`
+    return head + lines.join('\n')
+  }
+  // Nenhuma linha de assinatura encontrada — retorna source inalterado.
+  return source
+}
+
 // rewriteFrontmatterFields substitui as linhas "name:" e "description:" do
 // frontmatter de um markdown cru por name e description, preservando toda
 // outra linha do frontmatter byte a byte (ordem, espaçamento, estilo de
@@ -176,8 +224,10 @@ function frontmatterName(content) {
 //     gemini, cursor, copilot, kiro-ide, windsurf), retorna o source cru
 //     normalizado com o frontmatter ainda anexado. Quando há identidade
 //     configurada, suas linhas "name:"/"description:" são reescritas no
-//     lugar (ver rewriteFrontmatterFields) — necessário porque a seleção de
-//     subagent do Claude Code lê apenas o frontmatter, nunca o corpo.
+//     lugar (ver rewriteFrontmatterFields) e a última linha de assinatura do
+//     corpo com padrão `^— <nome>, <título>$` é reescrita com o display name
+//     da identidade (ver rewriteSignatureLine) — necessário porque a seleção
+//     de subagent do Claude Code lê apenas o frontmatter, nunca o corpo.
 //
 // Ambas as rotas devem receber a injeção de identidade. Quando não há
 // identidade configurada para item.id, name/description/body ficam
@@ -231,7 +281,8 @@ function render({ kind, content, capability, item, identity: cfg }) {
   if (!id) return normalize(content)
   const withBody = insertBodyPrefix(content, greeting)
   const withFrontmatter = rewriteFrontmatterFields(withBody, name, description)
-  return normalize(withFrontmatter)
+  const withSignature = rewriteSignatureLine(withFrontmatter, id.display_name)
+  return normalize(withSignature)
 }
 
-module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields }
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteSignatureLine }