featureparity 0.0.2 → 0.0.4

data/skills/fp/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: fp
+description: "Use the fp CLI to track feature parity: report evidence linking tests to requirements, propose new requirements as drafts, view the parity matrix, and upload test results from JUnit XML when CI isn't available."
+license: MIT
+compatibility: Requires the fp executable on PATH (gem install featureparity)
+metadata:
+  gem: featureparity
+  binary: fp
+---
+
+# fp — FeatureParity CLI
+
+Prefer the installed `fp` binary over inventing equivalent Ruby. Confirm it exists first:
+
+```bash
+command -v fp && fp --version
+```
+
+If missing: `gem install featureparity` (or `bundle exec fp` inside an app that already depends on the gem).
+
+## Non-interactive rules
+
+- Always pass flags. Never rely on prompts or TTY menus.
+- Use `--json` when parsing output programmatically.
+- Use `fp help <command>` before destructive commands.
+- Treat non-zero exit as failure; read stderr.
+
+## Authentication
+
+`fp` needs an API key. Check if configured:
+
+```bash
+# Environment variable (preferred for agents)
+echo $FP_API_KEY
+
+# Or via profile
+fp profile list
+```
+
+If not set, ask the user for their API key or have them run `fp setup`.
+
+## Core workflows
+
+### 1. Check existing requirements
+
+```bash
+fp list --project stowzilla                    # All active requirements
+fp list --project stowzilla --gaps             # Requirements without evidence
+fp show <slug> --project stowzilla             # Requirement details
+fp matrix --project stowzilla                  # ASCII parity matrix
+fp matrix --project stowzilla --csv            # Export as CSV
+```
+
+### 2. Add the fp:<slug> marker to tests
+
+Place a comment immediately before the test to bind it to a requirement:
+
+```ruby
+# fp:print_container_qr
+it 'prints a QR code onto the container label' do
+  expect(label.qr_code).to be_present
+end
+```
+
+**Rules:**
+- Use `fp:<slug>` where `<slug>` is the requirement's slug
+- Keep test names human-readable — the marker handles binding
+- Pin surfaces with `@suffix`: `fp:print_qr@api,web` reports for both surfaces
+
+### 3. Report evidence (single test)
+
+```bash
+fp report <slug> \
+  --project stowzilla \
+  --surface api \
+  --file spec/qr_spec.rb \
+  --repo stowzilla/marketplace \
+  --work-item https://app.fizzy.do/123/cards/456
+```
+
+**Required:** `<slug>`, `--project`, `--surface`, `--file`, `--repo`
+**Optional:** `--pr`, `--sha`, `--work-item`, `--ci-url`, `--title`
+
+**Agents report `present` (default) or `stub` only. Never `passing` or `failing`.**
+
+### 4. Report evidence from JUnit XML (batch upload without CI)
+
+When CI isn't available, run the suite locally and upload the report:
+
+```bash
+# 1. Generate JUnit XML
+rspec --format RspecJunitFormatter --out junit.xml
+
+# 2. Upload — one call covers every marked test
+fp report --junit junit.xml \
+  --project stowzilla \
+  --surface api \
+  --repo stowzilla/marketplace \
+  --work-item https://app.fizzy.do/123/cards/456
+```
+
+- No `<slug>` positional needed — slugs come from the `fp:<slug>` markers
+- Skipped tests become `stub`; all others `present`
+- Unknown slugs and unmarked tests are skipped with a warning
+- `--surface` is the default; markers can override with `@suffix`
+- `--base-dir DIR` sets where relative paths resolve from
+
+### 5. Propose new requirements
+
+```bash
+fp propose --project stowzilla \
+  --slug print_container_qr \
+  --name "Print QR on container label" \
+  --why "Enables scanning containers in the warehouse" \
+  --required api,customer_android \
+  --acceptance "Label shows scannable QR code"
+```
+
+**Agents always create requirements as draft.** A human must activate in the web app.
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| List requirements | `fp list --project X` |
+| Show gaps | `fp list --project X --gaps` |
+| Show details | `fp show <slug> --project X` |
+| Report evidence | `fp report <slug> --project X --surface Y --file Z --repo A/B` |
+| Report from JUnit | `fp report --junit file.xml --project X --surface Y --repo A/B` |
+| Propose requirement | `fp propose --project X --slug Y --name "..."` |
+| View matrix | `fp matrix --project X` |
+| List surfaces | `fp surfaces --project X` |
+| List projects | `fp projects` |
+
+All commands support `--json` for machine-readable output.
+
+## When to read more
+
+- Full flag reference and exit codes → `references/cli.md`
+- Marker syntax and examples → `references/markers.md`

data/skills/fp/references/cli.md

@@ -0,0 +1,245 @@
+# fp CLI Reference
+
+Complete flag reference for the `fp` command-line tool.
+
+## Global flags
+
+These work with any command:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output JSON instead of human-readable text |
+| `--profile NAME` | Use a named profile from `~/.config/fp/config.yml` |
+| `--api-url URL` | Override the API URL for this invocation |
+| `--help` | Show help for any command |
+
+## Commands
+
+### fp setup
+
+Interactive first-run configuration. Validates API key and saves a profile.
+
+```bash
+fp setup                                    # Interactive
+fp setup --api-key fp_... --non-interactive # Non-interactive
+fp setup --api-key fp_... --profile ci      # Named profile
+```
+
+### fp projects
+
+List accessible projects.
+
+```bash
+fp projects
+fp projects --json
+```
+
+### fp surfaces
+
+List surfaces for a project.
+
+```bash
+fp surfaces --project stowzilla
+fp surfaces --project stowzilla --json
+```
+
+### fp list
+
+List requirements.
+
+```bash
+fp list --project stowzilla              # All active requirements
+fp list --project stowzilla --gaps       # Requirements without evidence
+fp list --project stowzilla --status draft
+fp list --project stowzilla --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--project` | Project slug (required) |
+| `--gaps` | Show only requirements without evidence |
+| `--status` | Filter by status: active, draft, archived |
+| `--category` | Filter by category |
+
+### fp show
+
+Show requirement details.
+
+```bash
+fp show print_container_qr --project stowzilla
+fp show print_container_qr --project stowzilla --json
+```
+
+### fp report
+
+Report evidence linking a test to a requirement.
+
+**Single-slug mode:**
+
+```bash
+fp report <slug> \
+  --project stowzilla \
+  --surface api \
+  --file spec/qr_spec.rb \
+  --repo stowzilla/marketplace \
+  [--pr URL] [--sha COMMIT] [--work-item URL] [--ci-url URL] [--title "..."] [--state present|stub]
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `<slug>` | Yes | Requirement slug (positional) |
+| `--project` | Yes | Project slug |
+| `--surface` | Yes | Surface this evidence covers |
+| `--file` | Yes | Path to test file (relative to repo root) |
+| `--repo` | Yes | GitHub repo as `org/repo` |
+| `--pr` | No | Pull request URL |
+| `--sha` | No | Commit SHA |
+| `--work-item` | No | Fizzy card or issue URL |
+| `--ci-url` | No | CI run URL |
+| `--title` | No | Human-readable test name for display |
+| `--state` | No | `present` (default) or `stub`. Never `passing`/`failing` — that's CI's job. |
+
+**JUnit batch mode:**
+
+```bash
+fp report --junit junit.xml \
+  --project stowzilla \
+  --surface api \
+  --repo stowzilla/marketplace \
+  [--base-dir DIR] [--pr URL] [--sha COMMIT] [--work-item URL] [--ci-url URL]
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--junit` | Yes | Path to JUnit XML report |
+| `--project` | Yes | Project slug |
+| `--surface` | Conditional | Default surface for markers without `@suffix`. Required if any matched marker pins no surface. |
+| `--repo` | Yes | GitHub repo as `org/repo` |
+| `--base-dir` | No | Where to resolve relative file paths (defaults to cwd) |
+
+In JUnit mode:
+- Slugs come from `fp:<slug>` markers in the test files referenced by the report
+- A marker binds to the test directly below it
+- Skipped/pending tests become `stub`; all others `present`
+- Unknown slugs and unmarked tests are skipped with a warning
+
+### fp propose
+
+Propose a new requirement as draft.
+
+```bash
+fp propose --project stowzilla \
+  --slug print_container_qr \
+  --name "Print QR on container label" \
+  --why "Enables scanning containers" \
+  --required api,customer_android \
+  --acceptance "Label shows scannable QR code"
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--project` | Yes | Project slug |
+| `--slug` | Yes | Requirement slug (immutable, choose carefully) |
+| `--name` | Yes | Human-readable name |
+| `--why` | No | Why this requirement matters |
+| `--required` | No | Comma-separated surfaces that must implement this |
+| `--acceptance` | No | How to verify completion |
+
+**Agents always create requirements as draft.** A human must activate in the web app.
+
+### fp matrix
+
+Display the parity matrix.
+
+```bash
+fp matrix --project stowzilla           # ASCII table
+fp matrix --project stowzilla --csv     # CSV export
+fp matrix --project stowzilla --json    # JSON
+```
+
+### fp profile
+
+Manage named profiles. Each profile stores an API key and (optionally) the
+API URL and environment it targets, so a key is always tagged with the
+environment it talks to.
+
+```bash
+fp profile list
+fp profile add staging --api-key fp_... --api-url https://api.staging.featureparity.dev
+fp profile add staging --api-key fp_... --environment staging
+```
+
+If `--environment` is omitted it is derived from the API URL's host, following
+the Belt DNS convention (`infrastructure/modules/app/dns.tf`):
+
+- `api.featureparity.dev` → `production`
+- `api.staging.featureparity.dev` → `staging`
+- `api-abc-1234.dev.featureparity.dev` → `abc-1234` (nested/ephemeral env; `api-` prefix)
+- `localhost` / `127.0.0.1` → `local`
+
+`fp profile list` shows the tag.
+
+### fp config
+
+Manage global settings.
+
+```bash
+fp config list
+fp config get api_url
+fp config set api_url https://api.dev.featureparity.dev
+fp config unset api_url
+fp config whoami                 # alias of `fp whoami`
+```
+
+### fp whoami
+
+Show the *resolved* configuration this invocation would use — the active
+profile, the environment, the API URL (and where each value came from), and
+whether an API key is present (masked, never the full token). Makes no API
+calls, so it works even without a valid key.
+
+```bash
+fp whoami
+fp whoami --json
+fp --profile staging whoami       # inspect a specific profile
+fp --api-url http://localhost:9292 whoami
+```
+
+### fp repos
+
+Map surfaces to local repo paths (stored locally, not in the web app).
+
+```bash
+fp repos list --project stowzilla
+fp repos set customer_android ~/code/customer-android --project stowzilla --repo org/repo
+fp repos get customer_android --project stowzilla
+fp repos unset customer_android --project stowzilla
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error (invalid flags, missing required args, API error) |
+
+## Configuration files
+
+- `~/.config/fp/config.yml` — Profiles and global settings
+- `FP_API_KEY` environment variable overrides all profiles
+- `FP_API_URL` environment variable overrides API URL
+- `FP_PROFILE` environment variable selects a profile
+
+## API URL priority
+
+1. `--api-url` flag
+2. `FP_API_URL` environment variable
+3. Profile `api_url` setting
+4. Global `api_url` setting
+5. Default: `https://api.featureparity.dev`
+
+## Profile resolution priority
+
+1. `--profile` flag
+2. `FP_PROFILE` environment variable
+3. `default` profile (if it exists)

data/skills/fp/references/markers.md

@@ -0,0 +1,149 @@
+# fp Marker Syntax
+
+The `fp:<slug>` marker binds a test to a FeatureParity requirement. Place it as a comment immediately before the test definition.
+
+## Basic syntax
+
+```
+fp:<slug>
+```
+
+Where `<slug>` is the requirement's slug (lowercase, underscores, e.g., `print_container_qr`).
+
+## Surface pinning
+
+Pin one or more surfaces with the `@` suffix:
+
+```
+fp:<slug>@<surface>
+fp:<slug>@<surface1>,<surface2>
+```
+
+Examples:
+- `fp:print_qr` — uses `--surface` flag when reporting
+- `fp:print_qr@api` — reports for `api` surface only
+- `fp:print_qr@api,web` — reports for both `api` and `web`
+
+When using `fp report --junit`, each pinned surface produces a separate evidence upload.
+
+## Language examples
+
+### Ruby/RSpec
+
+```ruby
+# fp:print_container_qr
+it 'prints a QR code onto the container label' do
+  expect(label.qr_code).to be_present
+end
+
+# fp:print_container_qr@api,web
+it 'prints a QR code (backend test covering multiple surfaces)' do
+  expect(label.qr_code).to be_present
+end
+```
+
+### Kotlin/JUnit
+
+```kotlin
+// fp:print_container_qr
+@Test
+fun `prints a QR code onto the container label`() {
+    assertNotNull(label.qrCode)
+}
+
+// fp:print_container_qr@customer_android
+@Test
+fun `prints a QR code (Android-specific)`() {
+    assertNotNull(label.qrCode)
+}
+```
+
+### Swift/XCTest
+
+```swift
+// fp:print_container_qr
+func testPrintsQRCodeOntoContainerLabel() {
+    XCTAssertNotNil(label.qrCode)
+}
+
+// fp:print_container_qr@customer_ios
+func testPrintsQRCodeOniOS() {
+    XCTAssertNotNil(label.qrCode)
+}
+```
+
+### TypeScript/Jest
+
+```typescript
+// fp:print_container_qr
+it('prints a QR code onto the container label', () => {
+  expect(label.qrCode).toBeDefined();
+});
+
+// fp:print_container_qr@web
+it('prints a QR code (web-specific)', () => {
+  expect(label.qrCode).toBeDefined();
+});
+```
+
+### Python/pytest
+
+```python
+# fp:print_container_qr
+def test_prints_qr_code_onto_container_label():
+    assert label.qr_code is not None
+
+# fp:print_container_qr@api
+def test_prints_qr_code_api():
+    assert label.qr_code is not None
+```
+
+### Go
+
+```go
+// fp:print_container_qr
+func TestPrintsQRCodeOntoContainerLabel(t *testing.T) {
+    if label.QRCode == nil {
+        t.Fatal("expected QR code")
+    }
+}
+
+// fp:print_container_qr@api
+func TestPrintsQRCodeAPI(t *testing.T) {
+    if label.QRCode == nil {
+        t.Fatal("expected QR code")
+    }
+}
+```
+
+## Rules
+
+1. **One marker per test.** A marker binds to the test directly below it.
+
+2. **Human-readable test names.** The marker handles binding; don't name tests after slugs.
+   - ❌ `it 'print_container_qr' do`
+   - ✅ `it 'prints a QR code onto the container label' do`
+
+3. **Marker must be immediately before the test.** No blank lines or other code between the marker comment and the test definition.
+
+4. **Comment style follows language conventions.** Use `#` for Ruby/Python, `//` for Kotlin/Swift/TypeScript/Go.
+
+## Verification
+
+After adding a marker, verify it's findable:
+
+```bash
+grep -r "fp:print_container_qr" spec/
+```
+
+## JUnit binding
+
+When using `fp report --junit`, the CLI:
+
+1. Parses the JUnit XML report
+2. For each `<testcase>`, reads the `file` attribute to find the source file
+3. Scans the source file for `fp:<slug>` markers
+4. Binds each marker to the test directly below it
+5. Reports evidence for each binding
+
+Testcases without a marker are skipped with a warning. Markers with unknown slugs are also skipped.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -103,13 +103,19 @@ files:
 - lib/fp/commands/projects.rb
 - lib/fp/commands/propose.rb
 - lib/fp/commands/report.rb
+- lib/fp/commands/repos.rb
 - lib/fp/commands/setup.rb
 - lib/fp/commands/show.rb
 - lib/fp/commands/surfaces.rb
 - lib/fp/commands/version.rb
+- lib/fp/commands/whoami.rb
 - lib/fp/config.rb
+- lib/fp/junit.rb
 - lib/fp/output.rb
 - lib/fp/version.rb
+- skills/fp/SKILL.md
+- skills/fp/references/cli.md
+- skills/fp/references/markers.md
 homepage: https://featureparity.dev
 licenses:
 - MIT