faro-author-paths

Category: Tools & Productivity | Uploader: pmarchini | Downloads: 0 | Version: v1.0（Latest）

Create or update Faro path documents for this repository. Use when an agent needs to draft, refine, or replace a Faro path using the canonical schema from src/core/model/document.ts, while respecting the current MVP limits of linear paths, one active path, and one active beacon.

Changelog: Source: GitHub https://github.com/pmarchini/faro

Directory Structure

Current level: skills/faro-author-paths/

📄 SKILL.md 3.9 KB

SKILL.md

---
name: faro-author-paths
description: Create or update Faro path documents for this repository. Use when an agent needs to draft, refine, or replace a Faro path using the canonical schema from src/core/model/document.ts, while respecting the current MVP limits of linear paths, one active path, and one active beacon.
---

# Faro Author Paths

Use this skill when the user wants a Faro path to be created, revised, extended, or checked for validity.

## Source Of Truth

The canonical schema lives in:

- `src/core/model/document.ts`

Do not invent a parallel schema. Re-read that file if the shape is uncertain.

## Current Product Limits

Work within the current MVP constraints:

- linear `mainPath` only
- one active path at a time
- one active beacon at a time
- `schemaVersion` is `1`
- `activePathId` must be `null` or match an existing path id

Current contract operations are:

- `faro.listPaths`
- `faro.getPath`
- `faro.upsertPath`
- `faro.setActivePath`
- `faro.setCurrentBeacon`
- `faro.deletePath`

Faro now exposes a local stdio MCP server in VS Code for these operations. Only claim this when the current agent runtime actually exposes the `faro.*` tools. If the runtime does not expose them, produce valid Faro path data or a precise edit plan that fits the canonical model.

## Required Path Rules

For each `FaroPath`:

- `id` must be stable and unique within the document
- every id in `mainPath` must exist in `beacons`
- `current.beaconId` must be `null` or one of the ids in `mainPath`
- `current.index` must match the position of `current.beaconId`
- `beacons` is a dictionary keyed by beacon id

For each `Beacon`:

- `id` must match the dictionary key
- `fileUri` must use the `file://` scheme
- `range` is 1-based
- `range.endLine` must not be before `range.startLine`
- if start and end line are the same, `endColumn` must not be before `startColumn`

## Workflow

1. Identify the user goal or subsystem to explain.
2. Start with `faro.listPaths` when tools are available so you do not overwrite state blindly.
3. Use `faro.getPath` before revising an existing path.
4. Decide whether to create a new path or replace/update an existing one.
5. Prefer one `faro.upsertPath` whole-path write rather than many tiny state changes.
6. Keep the path narrow and linear unless the user explicitly asks for more.
7. Use `faro.setActivePath` only when the authored path should become the main reading path immediately.
8. Use `faro.setCurrentBeacon` only when the starting point should move after authoring.
9. Make titles and explanations concrete enough to be navigable.
10. Validate `mainPath`, `beacons`, and `current` consistency before returning.

## Output Preference

Prefer returning one of these:

- a full `FaroDocument` when the user wants the whole state
- a single `FaroPath` when the user wants one path created or replaced
- a precise edit plan when the runtime surface is not yet available

## Minimal Shape

```ts
type FaroDocument = {
  schemaVersion: 1;
  activePathId: string | null;
  paths: FaroPath[];
};

type FaroPath = {
  id: string;
  title?: string;
  goal?: string;
  mainPath: string[];
  branches?: unknown[];
  current?: {
    mode: "main";
    index: number;
    beaconId: string | null;
  };
  beacons: Record<string, {
    id: string;
    title?: string;
    fileUri: string;
    range: {
      startLine: number;
      startColumn: number;
      endLine: number;
      endColumn: number;
    };
    summary?: string;
    explanation?: string;
    tags?: string[];
    children?: string[];
  }>;
};
```

## Good Defaults

- use short stable path ids such as `auth-flow` or `cache-invalidation`
- keep `title` readable and `goal` explicit
- make `summary` concise and `explanation` slightly more detailed
- use tags only when they help navigation

## Avoid

- branch-heavy structures for the current MVP
- placeholder file URIs that are not `file://`
- mismatched beacon ids between `mainPath` and `beacons`
- claiming runtime features that do not exist yet

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

faro-author-paths

Directory Structure

SKILL.md

Report

Notice