Skip to content

me2resh/apexyard / .claude/skills/tech-vision

tech-vision

Verified

Interactive author for the architecture vision template — target, gap, migration, anti-scope, cadence.

FileKindSize
SKILL.mdskill md16.7 KB
lint.shexecutablescript466 B
tests/README.mdmarkdown3.1 KB
tests/smoke.shexecutablescript13.2 KB

tests/smoke.sh

View on GitHub
#!/usr/bin/env bash
# /tech-vision smoke test
#
# The /tech-vision skill is interactive — operator answers prompts section-by-section,
# the model assembles a populated vision.md. Its three load-bearing contracts:
#
#   1. The framework template at templates/architecture/vision.md has every
#      section the skill expects to populate.
#   2. portfolio_resolve_template architecture/vision.md returns the framework
#      default in single-fork mode, and the override in split-portfolio mode
#      when an override is dropped at custom-templates/architecture/vision.md.
#   3. The discoverable section list (## headings) matches the seven sections
#      named in SKILL.md so the interview drives off the template, not a
#      hardcoded list — and a populated vision built from those sections is
#      a structurally valid output.
#
# This test stubs the interactive layer by building a "populated vision" from
# the template's section list with synthetic answers, then asserts the result
# contains every required heading. If the template's headings drift, this
# catches it; if SKILL.md's contract drifts from the template, this catches
# it too.

set -uo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
HOOKS_DIR="$(cd "$SKILL_DIR/../../hooks" && pwd)"
OPS_ROOT="$(cd "$HOOKS_DIR/../.." && pwd)"

PASS=0
FAIL=0
FAILED_CASES=""

pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); FAILED_CASES="$FAILED_CASES\n  $1"; }

# ---------------------------------------------------------------------------
# Sanity: helper, template, and SKILL.md exist
# ---------------------------------------------------------------------------

echo ""
echo "================================================================"
echo "Sanity: framework artefacts present"
echo "================================================================"

if [ -f "$HOOKS_DIR/_lib-portfolio-paths.sh" ]; then
  pass "_lib-portfolio-paths.sh exists"
else
  fail "_lib-portfolio-paths.sh missing"
fi

if [ -f "$OPS_ROOT/templates/architecture/vision.md" ]; then
  pass "framework template at templates/architecture/vision.md exists"
else
  fail "framework template missing"
fi

if [ -f "$SKILL_DIR/SKILL.md" ]; then
  pass "SKILL.md exists"
else
  fail "SKILL.md missing"
fi

# ---------------------------------------------------------------------------
# Contract 1: every section named in SKILL.md is a ## heading in the template
# ---------------------------------------------------------------------------

echo ""
echo "================================================================"
echo "Contract 1: template headings match SKILL.md's interview shape"
echo "================================================================"

TEMPLATE="$OPS_ROOT/templates/architecture/vision.md"

# The seven sections SKILL.md drives the interview from.
REQUIRED_HEADINGS=(
  "Scope"
  "Principles"
  "Target-state architecture"
  "Current state vs target state"
  "Migration path"
  "Things we explicitly chose NOT to build"
  "Review cadence"
)

for heading in "${REQUIRED_HEADINGS[@]}"; do
  if grep -qE "^##[[:space:]]+${heading}\$" "$TEMPLATE"; then
    pass "template has '## ${heading}'"
  else
    fail "template missing '## ${heading}' — SKILL.md interview shape drifted"
  fi
done

# ---------------------------------------------------------------------------
# Contract 2: portfolio_resolve_template returns the framework default by
# default, and a custom override when one is present in a fake portfolio
# ---------------------------------------------------------------------------

echo ""
echo "================================================================"
echo "Contract 2: portfolio_resolve_template architecture/vision.md"
echo "================================================================"

# Source the helper. It uses git rev-parse to locate the ops root, which is
# tricky in a worktree — but the helper also walks up from CWD to find an
# ops-fork anchor. We just need to call it from inside the ops root.

# shellcheck source=/dev/null
source "$HOOKS_DIR/_lib-read-config.sh"
# shellcheck source=/dev/null
source "$HOOKS_DIR/_lib-portfolio-paths.sh"

# In single-fork mode (no portfolio: config block), the resolver should walk
# the registry's parent dir for custom-templates/architecture/vision.md, then
# fall through to the framework default.
resolved=$(cd "$OPS_ROOT" && portfolio_resolve_template architecture/vision.md 2>/dev/null || echo "")

if [ -n "$resolved" ] && [ -f "$resolved" ]; then
  pass "resolver returned an existing file: $(basename "$(dirname "$resolved")")/$(basename "$resolved")"
else
  fail "resolver did not return a usable path (got: '$resolved')"
fi

# The default resolution should match the framework template (no custom
# override present in the current checkout). The test forks here only if an
# adopter happens to have committed a custom override, which the framework
# repo doesn't ship.
if [ -n "$resolved" ] && [ "$resolved" = "$TEMPLATE" ]; then
  pass "resolver returns framework default when no override exists"
elif [ -n "$resolved" ]; then
  # Adopter override present — that's also a valid pass, just note it.
  pass "resolver returns adopter override: $resolved (framework default also exists at $TEMPLATE)"
else
  fail "resolver returned empty"
fi

# Now build a fake portfolio with a custom template and assert the resolver
# picks it up. Layout:
#   $TMPDIR/fake-private-repo/
#     ├── apexyard.projects.yaml        ← anchors portfolio_registry
#     └── custom-templates/
#         └── architecture/
#             └── vision.md             ← the override
#
# We can't reconfigure the resolver from inside a test without writing a
# project-config.json, which would mutate the real repo. So instead, just
# assert the resolution rule directly: when a file exists at
# <registry_parent>/custom-templates/<rel>, it should win.

TMPROOT=$(mktemp -d -t tech-vision-resolver-XXXXXX)
trap 'rm -rf "$TMPROOT"' EXIT

mkdir -p "$TMPROOT/fake-private/custom-templates/architecture"
cat > "$TMPROOT/fake-private/apexyard.projects.yaml" <<'YAML'
version: 1
projects: []
YAML
cat > "$TMPROOT/fake-private/custom-templates/architecture/vision.md" <<'MD'
# Custom Architecture Vision — {Project Name}

## Scope
custom scope intro

## Principles
custom principles intro

## Target-state architecture
custom target-state intro

## Current state vs target state
custom current-vs-target intro

## Migration path
custom migration intro

## Things we explicitly chose NOT to build
custom anti-scope intro

## Review cadence
custom review-cadence intro
MD

# Manually mirror what portfolio_resolve_template does:
#   1. registry=<TMPROOT>/fake-private/apexyard.projects.yaml
#   2. custom_dir=$(dirname "$registry") = <TMPROOT>/fake-private
#   3. check $custom_dir/custom-templates/architecture/vision.md
custom_path="$TMPROOT/fake-private/custom-templates/architecture/vision.md"
if [ -f "$custom_path" ]; then
  pass "custom override path exists in fake portfolio — resolver step 1 would return it"
else
  fail "custom override path was not seeded correctly"
fi

# ---------------------------------------------------------------------------
# Contract 3: a populated vision built from the template's section list is
# structurally valid — every required ## heading appears in the output, the
# anti-scope section has at least one item with a "reconsider when" clause,
# and the migration table is non-empty
# ---------------------------------------------------------------------------

echo ""
echo "================================================================"
echo "Contract 3: structurally valid output from the template's sections"
echo "================================================================"

OUT=$(mktemp -t tech-vision-output-XXXXXX).md
trap 'rm -rf "$TMPROOT" "$OUT"' EXIT

# Build a synthetic populated vision that mimics what the skill would write
# after a successful interview. The shape is: every ## heading from the
# template, plus a one-line populated body per section, plus the skill
# footer.
{
  echo "# Architecture Vision — fixture-app"
  echo ""
  echo "> North-star architecture for the fixture-app system."
  echo ""
  for heading in "${REQUIRED_HEADINGS[@]}"; do
    echo "## ${heading}"
    echo ""
    case "$heading" in
      "Scope")
        echo "Covers the fixture-app customer-facing web platform — onboarding, orders, account self-service."
        ;;
      "Principles")
        echo "1. **Bounded contexts own their data** — no cross-context DB joins."
        echo "2. **Failures are caller-handled** — services surface typed errors."
        echo "3. **Idempotency by default** — every state-changing endpoint accepts an idempotency key."
        echo "4. **Observability is a feature** — every service ships with structured logs + metrics."
        echo "5. **Strict-typed boundaries** — every public interface has a versioned schema."
        ;;
      "Target-state architecture")
        echo '```mermaid'
        echo 'C4Context'
        echo '    title Target-state System Context for fixture-app'
        echo '    Person(user, "Customer", "End user")'
        echo '    System(main, "fixture-app", "Order management")'
        echo '    System_Ext(stripe, "Stripe", "Payments")'
        echo '    Rel(user, main, "Uses", "HTTPS")'
        echo '    Rel(main, stripe, "Charges", "HTTPS")'
        echo '```'
        ;;
      "Current state vs target state")
        echo "| Dimension | Today | Target | Gap |"
        echo "|-----------|-------|--------|-----|"
        echo "| Data layer | shared Postgres | per-context Postgres | extract billing tables |"
        echo "| Auth | session cookies | OIDC | migrate to claims |"
        echo "| Deployment | EC2 + script | ECS + GHA | containerise services |"
        echo "| Observability | CloudWatch logs only | OTEL + Datadog | instrument services |"
        ;;
      "Migration path")
        echo "| Quarter | Milestone | Owner | Done when |"
        echo "|---------|-----------|-------|-----------|"
        echo "| Q1 26 | Extract billing tables | Tech Lead — billing | cross-context joins fail in staging |"
        echo "| Q2 26 | Introduce event bus | Tech Lead — platform | welcome email via UserRegistered event |"
        echo "| Q3 26 | OIDC migration | Tech Lead — auth | session cookies retired |"
        ;;
      "Things we explicitly chose NOT to build")
        echo "- **Microservices below the bounded-context level** — *Rationale: a 10-service split is more painful than a well-bounded modular monolith at our scale. Reconsider when org > 50 engineers.*"
        echo "- **Multi-region active-active** — *Rationale: single-region customer base today; data-residency cost outweighs latency win. Reconsider when expansion lands in a second geographic region.*"
        echo "- **Custom auth provider** — *Rationale: identity is not a differentiator; vendor lock-in acceptable. Reconsider only on a vendor exit event.*"
        ;;
      "Review cadence")
        echo "Reviewed **quarterly** by Tech Lead + Head of Engineering."
        ;;
    esac
    echo ""
  done

  echo "---"
  echo ""
  echo "_Generated by \`/tech-vision\` on $(date +%Y-%m-%d). Re-run quarterly._"
} > "$OUT"

# Now assert: every required heading is in the output
for heading in "${REQUIRED_HEADINGS[@]}"; do
  if grep -qE "^##[[:space:]]+${heading}\$" "$OUT"; then
    pass "output contains '## ${heading}'"
  else
    fail "output missing '## ${heading}'"
  fi
done

# Anti-scope must have at least one "Reconsider when" rationale
if grep -qE "[Rr]econsider when" "$OUT"; then
  pass "anti-scope has 'reconsider when' rationale (load-bearing per template note)"
else
  fail "anti-scope missing 'reconsider when' clause — section is filler without it"
fi

# Migration path must be a non-trivial table (header + at least one data row)
MIGRATION_ROWS=$(awk '/^## Migration path/{flag=1; next} /^## /{flag=0} flag && /^\| Q/' "$OUT" | wc -l | tr -d ' ')
if [ "$MIGRATION_ROWS" -ge 1 ]; then
  pass "migration path has $MIGRATION_ROWS milestone row(s)"
else
  fail "migration path has no milestone rows"
fi

# Current-vs-target table must have at least one row
CVT_ROWS=$(awk '/^## Current state vs target state/{flag=1; next} /^## /{flag=0} flag && /^\| [A-Z]/' "$OUT" | wc -l | tr -d ' ')
if [ "$CVT_ROWS" -ge 1 ]; then
  pass "current-vs-target table has $CVT_ROWS dimension row(s)"
else
  fail "current-vs-target table has no dimension rows"
fi

# Skill footer signature is present
if grep -qE "^_Generated by \`/tech-vision\`" "$OUT"; then
  pass "skill footer signature present"
else
  fail "skill footer signature missing"
fi

# Mermaid block for target-state diagram is present
if grep -qE "^\`\`\`mermaid\$" "$OUT"; then
  pass "target-state Mermaid C4 block present"
else
  fail "target-state Mermaid block missing"
fi

# ---------------------------------------------------------------------------
# Summary
# ---------------------------------------------------------------------------

echo ""
echo "----------------------------------------"
echo "Total: $((PASS + FAIL))   Passed: $PASS   Failed: $FAIL"
echo "----------------------------------------"

if [ "$FAIL" -gt 0 ]; then
  echo ""
  echo "Failed cases:"
  printf "%b\n" "$FAILED_CASES"
  exit 1
fi

echo ""
echo "OK: all /tech-vision contract checks passed."
exit 0
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall