me2resh/apexyard / .claude/skills/tech-vision
tech-vision
VerifiedInteractive author for the architecture vision template — target, gap, migration, anti-scope, cadence.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.7 KB |
| lint.shexecutable | script | 466 B |
| tests/README.md | markdown | 3.1 KB |
| tests/smoke.shexecutable | script | 13.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |