featureparity 0.0.1 → 0.0.3

data/skills/fp/references/cli.md

@@ -0,0 +1,219 @@
+# 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.
+
+```bash
+fp profile list
+fp profile add staging --api-key fp_...
+fp profile remove staging
+fp profile show staging
+```
+
+### 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 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.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -95,6 +95,7 @@ files:
 - lib/fp/client.rb
 - lib/fp/commands.rb
 - lib/fp/commands/base.rb
+- lib/fp/commands/config_cmd.rb
 - lib/fp/commands/help.rb
 - lib/fp/commands/list.rb
 - lib/fp/commands/matrix.rb
@@ -102,13 +103,18 @@ 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/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