janderscience-skills 0.0.0-stage → 1.0.0

package/sources/headcount/plugins/security/skills/incident-response/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: incident-response
+description: Runs a security incident from detection to closure — triage, containment, investigation, communication, and the review afterward. Use this when a compromise is suspected or confirmed, when preparing an incident response plan or running an exercise, when deciding whether something is an incident, or when a breach may trigger notification obligations.
+---
+
+# Incident response
+
+> Breach notification runs on statutory clocks, measured in hours in several regimes. Involve Legal
+> & Risk and qualified counsel as soon as personal data may be involved — not after the technical
+> work is done.
+
+## Decide it is an incident, and say so
+
+The most expensive delay is the hour spent debating whether this is really an incident. Declare
+early; standing down a declared incident is cheap, and discovering an hour late that it was real is
+not.
+
+Name an **incident commander** immediately. One person, coordinating, not doing the technical work.
+Everyone else has a defined job. Incidents fail on coordination far more than on technical
+capability.
+
+## Order of operations
+
+**1. Contain before investigating.** Stop the bleeding: isolate the host, revoke the credential,
+disable the account, block the path. It is tempting to watch the attacker to learn more — do that
+only with a deliberate decision, not by default.
+
+**2. Preserve evidence while containing.** Snapshot before you rebuild. Capture volatile state —
+memory, connections, running processes — before powering anything off. Rebuilding a compromised host
+destroys the only record of how they got in, and you will need it.
+
+**3. Establish scope.** What was accessed, what was taken, when it started, and whether it is still
+happening. Assume the initial scope is understated; it usually is. Look for persistence and lateral
+movement before declaring containment.
+
+**4. Eradicate and recover.** Remove the access, close the path, then restore. Rebuild from known
+good rather than cleaning in place — you cannot prove a cleaned host is clean.
+
+Rotate every credential the attacker could have reached, not only the ones you know they used.
+
+**5. Watch after recovery.** Re-entry is common. Monitor specifically for the path they used and its
+neighbors.
+
+## Communication
+
+Keep one timeline as the single source of truth, updated as facts are established, with each entry
+timestamped and attributed. Incidents generate contradictory information at speed, and the timeline
+is what stops the same question being answered three ways.
+
+Say what is known, what is not yet known, and when the next update comes. Never speculate on cause
+or scope externally before it is established — a retracted statement extends the story and damages
+credibility more than the incident did.
+
+## Afterward
+
+Blameless review, focused on the system rather than the person. The useful questions: how could this
+have been detected sooner, what made containment slow, what did we not have that we needed, and what
+made this possible in the first place.
+
+Output actions with owners and dates. A review producing no committed changes is theater, and the
+same incident recurs.
+
+## Preparation
+
+The plan matters less than having run it. Exercise once a year at minimum: a tabletop against a
+realistic scenario finds the gaps — who has authority out of hours, where the credentials are, who
+calls counsel — at a time when finding them is free.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Rebuild or wipe a compromised host before evidence is captured.
+- Let the person running the technical response also own external communication.
+- Close an incident before you can say how entry happened and that the path is shut.
+- Speculate about cause or attribution outside the response channel while the incident is open.

package/sources/headcount/plugins/security/skills/incident-response/references/sources.md

@@ -0,0 +1,37 @@
+# Sources — `security:incident-response`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## CISA Known Exploited Vulnerabilities Catalog
+
+CISA · US · public domain (US government) — quote freely
+
+<https://www.cisa.gov/known-exploited-vulnerabilities-catalog>
+
+Machine-readable: <https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json>
+
+**Authoritative for:** Which vulnerabilities are being exploited in the wild right now — the only list that reliably separates patch-this-week from patch-this-quarter.
+
+## MITRE ATT&CK
+
+The MITRE Corporation · global · free to use with attribution — credit the publisher
+
+<https://attack.mitre.org/>
+
+Machine-readable: <https://github.com/mitre-attack/attack-stix-data>
+
+**Authoritative for:** The shared vocabulary for adversary tactics and techniques — what to name a behavior so a detection, a threat model and an incident report refer to the same thing.
+
+## NIST SP 800-61: Incident Response Recommendations and Considerations
+
+NIST · US · public domain (US government) — quote freely
+
+<https://csrc.nist.gov/pubs/sp/800/61/r3/final>
+
+**Authoritative for:** What an incident response capability must contain and what evidence must be captured at each stage. The current revision is a substantial rewrite that drops the older four-phase framing, so do not mix guidance across revisions.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/security/skills/security-architecture-review/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: security-architecture-review
+description: Reviews a design or change for security before it ships — authentication and authorization, data handling, secrets, dependencies, and the secure-development practices around it. Use this to review an architecture or pull request for security, set secure coding standards, choose or tune SAST and DAST tooling, assess a third-party integration, or decide whether a design is safe to build.
+---
+
+# Security architecture review
+
+## Review in this order
+
+Attention spent in this order finds the most consequential problems first.
+
+**1. Authentication.** How identity is established, how sessions are represented, how they expire,
+what happens on password reset and account recovery. Recovery flows are the most commonly weakest
+path into an account and the least reviewed.
+
+**2. Authorization.** The one that matters most and gets least attention. For every endpoint and
+every object: who is allowed, and where is that checked? The characteristic failure is checking on
+the way in but not on the object itself, so any authenticated user can reach any record by changing
+an identifier.
+
+Check multi-tenant isolation explicitly and by test, not by reading. Assume every identifier in a
+request is attacker-controlled, because it is.
+
+**3. Data.** What is collected, where it goes, where it rests, and who can read it. Sensitive data
+in logs, in error responses, in analytics payloads, and in client bundles — all four are routine
+findings.
+
+**4. Input and output.** Untrusted input reaching a query, a template, a command, a deserializer, or
+a URL the server fetches. Parameterize rather than escape. Validate against an allowlist rather than
+a denylist.
+
+**5. Secrets.** Never in source, never in client bundles, never in build logs. Rotatable, scoped to
+what needs them, and with a documented rotation path that someone has actually walked.
+
+**6. Dependencies and supply chain.** What is pulled in, how it is pinned, how updates are reviewed,
+and what would happen if a maintainer account were compromised. Lockfiles committed, builds
+reproducible.
+
+## Reviewing a change rather than a design
+
+Look for: new endpoints without an authorization check, new external input, changed authentication
+or session logic, new dependencies, anything touching cryptography, and anything that widens what a
+role can do. Everything else is usually lower yield.
+
+**Never write your own cryptography.** Use the vetted primitives, and be suspicious of any diff that
+implements a comparison, a token, or a signature by hand.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Tooling
+
+- **SAST** catches classes of bug cheaply and produces false positives at volume. Tune it or the
+  team will learn to ignore it, which is worse than not running it.
+- **DAST** and dependency scanning find different things; neither replaces review.
+- **Secret scanning in CI and pre-commit** is the highest-value automation per unit of effort.
+
+By name today: Semgrep, CodeQL, or SonarQube for SAST; Snyk, Dependabot, or Trivy for
+dependencies; Burp Suite or OWASP ZAP for DAST; gitleaks, TruffleHog, or GitHub secret
+scanning for secrets — and similar in each category.
+
+Automation is a floor, not a review. It finds known patterns, not design flaws — and design flaws
+are what actually cause the expensive incidents.
+
+## Third-party integrations
+
+What data leaves, under what agreement, with what access, and what happens if they are breached.
+Scope credentials to the minimum, prefer short-lived tokens, and know how to revoke without an
+outage.
+
+## Never
+
+- Approve a design on the promise of a control with no named owner and no date.
+- Accept "it is internal" as an authorization boundary.
+- Review the diagram instead of the change. Read what is actually being built.
+- Sign off on a third-party integration without knowing what data leaves and under what terms.
+
+## Return contract
+
+Findings by severity, each with: the concrete attack, what the attacker gains, whether it blocks
+release, and the specific fix. A finding with no attack path stated is a preference.

package/sources/headcount/plugins/security/skills/security-architecture-review/references/sources.md

@@ -0,0 +1,63 @@
+# Sources — `security:security-architecture-review`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## FedRAMP baselines and automation content
+
+GSA · US · public domain (US government) — quote freely
+
+<https://www.fedramp.gov/rev5/documents-templates/>
+
+Machine-readable: <https://github.com/GSA/fedramp-automation>
+
+**Authoritative for:** Which SP 800-53 controls apply at low, moderate and high impact for a cloud service selling to the US federal government, and the evidence each requires.
+
+## MITRE ATT&CK
+
+The MITRE Corporation · global · free to use with attribution — credit the publisher
+
+<https://attack.mitre.org/>
+
+Machine-readable: <https://github.com/mitre-attack/attack-stix-data>
+
+**Authoritative for:** The shared vocabulary for adversary tactics and techniques — what to name a behavior so a detection, a threat model and an incident report refer to the same thing.
+
+## NIST Cybersecurity Framework 2.0
+
+NIST · US · public domain (US government) — quote freely
+
+<https://www.nist.gov/cyberframework>
+
+**Authoritative for:** The outcome-based vocabulary — govern, identify, protect, detect, respond, recover — that boards and customers most often ask a security program to map to.
+
+## NIST SP 800-53 Rev. 5 — Security and Privacy Controls for Information Systems
+
+NIST · US · public domain (US government) — quote freely
+
+<https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final>
+
+Machine-readable: <https://github.com/usnistgov/oscal-content>
+
+**Authoritative for:** The control catalog US federal systems are assessed against, and the control vocabulary FedRAMP and many private frameworks inherit.
+
+## OWASP Application Security Verification Standard
+
+OWASP Foundation · global · CC BY-SA — quote with attribution; share-alike, so do not fold into this repository
+
+<https://owasp.org/ASVS/>
+
+**Authoritative for:** Testable application security requirements at three assurance levels — the thing to write into a spec when 'make it secure' needs to become acceptance criteria.
+
+## OWASP Top 10
+
+OWASP Foundation · global · CC BY-SA — quote with attribution; share-alike, so do not fold into this repository
+
+<https://owasp.org/www-project-top-ten/>
+
+**Authoritative for:** The application-security risk categories a customer questionnaire or a pen-test report will be organized around.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/security/skills/threat-modeling/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: threat-modeling
+description: Identifies what could go wrong in a system before it is built or changed — the assets worth attacking, the entry points, the trust boundaries, and the controls that actually address the realistic threats. Use this when designing a feature or system, when a change touches authentication, data handling, payments, or external input, before a security review, or when deciding which security work is worth doing at all.
+---
+
+# Threat modeling
+
+Done at design time this is cheap and changes the design. Done after launch it produces a list of
+things that are expensive to fix, so the timing is most of the value.
+
+## Four questions, in order
+
+**1. What are we building?** A diagram of the actual data flow — not the org chart, not the
+marketing architecture. Components, the data moving between them, and where each store lives. If
+nobody can draw it, that is the first finding.
+
+Mark the **trust boundaries**: every point where data crosses from something you control to
+something you do not, or from one privilege level to another. Almost every real vulnerability lives
+on a boundary.
+
+**2. What can go wrong?** Walk each boundary and each asset. A usable prompt set:
+
+- **Spoofing** — can someone claim to be another user, service, or system?
+- **Tampering** — can data be modified in transit, at rest, or in the client?
+- **Repudiation** — can someone deny an action, and would we be able to show otherwise?
+- **Information disclosure** — what leaks: to other users, to logs, to error messages, to the
+  client bundle?
+- **Denial of service** — what is unbounded? Uploads, queries, retries, fan-out.
+- **Elevation of privilege** — can a user reach data or actions belonging to another tenant, role,
+  or account?
+
+Two that catch more real bugs than the classic list: **what does the client enforce that the server
+does not**, and **what happens on the second attempt** — replay, race, and double-submit.
+
+**3. What are we going to do about it?** For each realistic threat: mitigate, transfer, avoid, or
+accept. Accepting is legitimate; accepting silently is not.
+
+Prioritize by attacker effort against impact, not by how alarming it sounds. A trivially exploitable
+tenant-isolation bug outranks a theoretical timing attack every time.
+
+**4. Did we do a good job?** Re-check the model when the design changes. A threat model that
+describes last quarter's architecture is worse than none, because it produces false confidence.
+
+## Scoping
+
+Model per feature or per boundary, not per system. A whole-system model is too big to finish and too
+vague to act on.
+
+Timebox it. An hour on a specific feature with the engineers who will build it beats a week-long
+exercise producing a document nobody reads.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Model the system as designed rather than as built. Ask what actually got shipped.
+- Assume internal traffic is trusted. That assumption is what turns one compromised service into
+  an incident.
+- Accept "the framework handles that" without checking that it is configured to.

package/sources/headcount/plugins/security/skills/threat-modeling/references/sources.md

@@ -0,0 +1,27 @@
+# Sources — `security:threat-modeling`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## MITRE ATT&CK
+
+The MITRE Corporation · global · free to use with attribution — credit the publisher
+
+<https://attack.mitre.org/>
+
+Machine-readable: <https://github.com/mitre-attack/attack-stix-data>
+
+**Authoritative for:** The shared vocabulary for adversary tactics and techniques — what to name a behavior so a detection, a threat model and an incident report refer to the same thing.
+
+## OWASP Top 10
+
+OWASP Foundation · global · CC BY-SA — quote with attribution; share-alike, so do not fold into this repository
+
+<https://owasp.org/www-project-top-ten/>
+
+**Authoritative for:** The application-security risk categories a customer questionnaire or a pen-test report will be organized around.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/security/skills/vulnerability-management/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: vulnerability-management
+description: Runs the loop from discovering a weakness to confirming it is fixed — scanning, triage, prioritization by real exploitability, remediation tracking, and patch policy. Use this to stand up or fix a vulnerability program, triage scanner output, decide what to fix first, set patch SLAs, handle a disclosure from an outside researcher, or report posture to leadership.
+---
+
+# Vulnerability management
+
+Scanners are cheap and produce more findings than any team can fix. The whole discipline is deciding
+what actually matters and closing those.
+
+## Prioritize by exploitability, not by score
+
+A published severity score describes the vulnerability in the abstract. What matters is your
+instance of it. Rank by:
+
+- **Is it reachable?** Internet-facing beats internal beats unreachable code path by a wide margin. A
+  critical in a dependency you import but never call is not a critical for you.
+- **Is it being exploited in the wild?** Known-exploited status should outrank a higher score that
+  nobody is using.
+- **What does exploitation yield here?** Compromise of the system holding customer data outranks the
+  same bug on a build agent.
+- **Is there a compensating control**, and does it actually work?
+
+A queue sorted purely by severity guarantees the team spends its time on the wrong things while a
+medium-rated, internet-facing, actively exploited bug waits.
+
+## Triage discipline
+
+Every finding gets one of four outcomes, each recorded: **fix**, **mitigate**, **accept** (with an
+expiry and a named owner), or **false positive** (with the reason).
+
+Nothing sits untriaged. An unreviewed backlog of thousands is the normal failure mode and it means
+the program is not running, whatever the dashboard says.
+
+Tune the scanner. Persistent false positives train the team to dismiss everything, including the
+real finding.
+
+## Patch policy
+
+Set SLAs by severity and exposure, publish them, and measure against them. Then measure the number
+that breach the SLA — that number, not the raw count, is the health of the program.
+
+Have an emergency path for actively exploited vulnerabilities that bypasses the normal cycle, agreed
+in advance. Deciding how to ship an out-of-band patch during the incident wastes the hours that
+matter.
+
+## Dependencies
+
+Most findings will be in third-party code. Keep dependencies current continuously rather than in
+large periodic jumps — a small regular upgrade is routine, a two-year jump is a project, and the
+project gets deferred.
+
+Know what you actually ship. A dependency inventory you cannot produce means you cannot answer "are
+we affected" when the next widely-exploited library bug lands, and that question arrives with a
+clock attached.
+
+## External disclosure
+
+Publish a way to report a vulnerability and an address that is monitored. Researchers who cannot
+find one disclose publicly instead.
+
+Acknowledge quickly, give a realistic timeline, keep them updated, and credit them. Treating a
+good-faith reporter as an adversary is how a private report becomes a public one.
+
+## Reporting
+
+Leadership needs: what is exposed and unfixed past SLA, the trend, and what needs a decision. Not
+the count of findings, which mostly measures how much you scanned.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Tooling
+
+Infrastructure scanning: Tenable, Qualys, Rapid7 InsightVM, and similar. Code and
+dependencies: Snyk, Dependabot, GitHub Advanced Security, Semgrep, Trivy, and similar.
+Cloud posture: Wiz, Orca, Prisma Cloud, and similar.
+
+Exploitability context — the CISA KEV catalog, EPSS scores — decides what you fix first.
+The scanner only decides what you know about.
+
+## Never
+
+- Rank on CVSS alone. A score is not exploitability in your environment.
+- Accept a risk without a named accepting owner and a date it gets revisited.
+- Push a patch to production without knowing what it changes and how to roll it back.
+- Report a shrinking backlog that shrank by reclassification rather than by remediation.

package/sources/headcount/plugins/security/skills/vulnerability-management/references/sources.md

@@ -0,0 +1,37 @@
+# Sources — `security:vulnerability-management`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## CISA Known Exploited Vulnerabilities Catalog
+
+CISA · US · public domain (US government) — quote freely
+
+<https://www.cisa.gov/known-exploited-vulnerabilities-catalog>
+
+Machine-readable: <https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json>
+
+**Authoritative for:** Which vulnerabilities are being exploited in the wild right now — the only list that reliably separates patch-this-week from patch-this-quarter.
+
+## NIST SP 800-40: Guide to Enterprise Patch Management Planning
+
+NIST · US · public domain (US government) — quote freely
+
+<https://csrc.nist.gov/pubs/sp/800/40/r4/final>
+
+**Authoritative for:** What a defensible patch program contains — maintenance windows, phased deployment, and the position that leaving something unpatched requires documented compensating controls rather than silence.
+
+## National Vulnerability Database
+
+NIST · US · public domain (US government) — quote freely
+
+<https://nvd.nist.gov/>
+
+Machine-readable: <https://nvd.nist.gov/developers/vulnerabilities>
+
+**Authoritative for:** CVE records with severity scoring and affected-version data, and the API a vulnerability program queries rather than reads.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/technology/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "technology",
+  "description": "Architecture, engineering delivery, development discipline, debugging, review, and AI and automation systems.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Chris Brock"
+  },
+  "repository": "https://github.com/cbrock84/headcount",
+  "keywords": [
+    "engineering",
+    "tdd",
+    "debugging",
+    "code-review",
+    "automation"
+  ]
+}

package/sources/headcount/plugins/technology/.codex-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "technology",
+  "version": "1.0.0",
+  "description": "Architecture, engineering delivery, development discipline, debugging, review, and AI and automation systems.",
+  "author": {
+    "name": "Chris Brock"
+  },
+  "repository": "https://github.com/cbrock84/headcount",
+  "license": "MIT",
+  "keywords": [
+    "engineering",
+    "tdd",
+    "debugging",
+    "code-review",
+    "automation"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Technology",
+    "category": "Productivity",
+    "shortDescription": "Technology, as an installable department",
+    "longDescription": "Architecture, engineering delivery, development discipline, debugging, review, and AI and automation systems.",
+    "developerName": "Chris Brock"
+  }
+}

package/sources/headcount/plugins/technology/skills/ai-workflow-architect/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: ai-workflow-architect
+description: Designs AI systems, automations, and agent workflows for a business — identifying which manual work is worth automating, how to structure the system, which tools fit, and what could go wrong. Use this to automate part of an operation, design an agent or MCP workflow, reduce repetitive manual work, connect tools into a system, decide which automation to build first, or audit an automation that is not delivering.
+---
+
+# AI workflow architect
+
+Most automation fails on selection, not implementation. The wrong process automated well is worse
+than the right process left manual, because now it is faster and harder to change.
+
+## What is worth automating
+
+Score each candidate on four dimensions and require a real answer to each:
+
+- **Frequency** — how often, honestly measured. Weekly is usually the floor.
+- **Time cost** — per occurrence, times frequency. Most "huge time sinks" are twenty minutes a week.
+- **Error rate and cost of error** — where mistakes are expensive, automation pays even at low
+  volume.
+- **Stability** — how often the process itself changes. A process that changes monthly will break
+  monthly.
+
+Then apply the disqualifiers. Do not automate a process that:
+
+- **Nobody has documented.** Automating an unexamined process encodes its accidents permanently.
+- **Requires judgment you cannot specify.** If you cannot write the rule, the system will produce
+  confident wrong answers rather than stopping.
+- **Fails silently.** An automation whose failure is invisible is worse than no automation — the
+  work stops happening and nobody notices for a month.
+- **Should be eliminated instead.** The best automation is deleting the step. Ask this before
+  designing anything.
+
+## Designing the system
+
+Start with the smallest loop that delivers value end to end, not the full vision. Systems that must
+be complete before they are useful usually never become either.
+
+- **Deterministic where you can, model-driven where you must.** Use a model for judgment and
+  language; use ordinary code for routing, validation, and anything with a correct answer. Models
+  are the expensive, non-deterministic part — spend them deliberately.
+- **Put a human at the consequential step**, not at every step. Approval on an irreversible action;
+  no approval on a draft.
+- **Make failure loud.** Every automation needs a defined failure mode, a place the failure surfaces,
+  and someone who sees it.
+- **Idempotence matters more than it seems.** Reruns happen. A workflow that double-sends on retry
+  will eventually double-send.
+
+## Designing specialized assistants
+
+Where a workflow needs judgment repeatedly, define a role rather than writing a prompt each time.
+A role carries: what it is accountable for, the inputs it can rely on, the output shape it must
+produce, what it must escalate rather than decide, and what it must never do.
+
+Keep roles narrow. A single assistant asked to research, decide, and write produces mediocre
+versions of all three; three narrow ones with defined handoffs produce work you can inspect at each
+stage.
+
+Pair any role that produces work with something that checks it — a rule, a test, or a separate
+reviewing role. A role that reviews its own output approves it.
+
+## Scoring candidates
+
+Score each automation candidate on frequency, time cost, error cost, and stability from one to five,
+then multiply rather than average — multiplication makes a low score on any dimension disqualifying,
+which is the correct behavior. A daily task that changes weekly should not survive on frequency
+alone.
+
+Rank by score ÷ build effort, and take the top item only. Automation programs fail by starting
+four things.
+
+## Choosing tools
+
+Match to the constraint that actually binds — volume, latency, existing stack, who maintains it, and
+what happens when the vendor changes terms. Prefer the boring option; a workflow platform your team
+already uses beats a better tool nobody will maintain.
+
+Where an agent needs access to systems, prefer a defined tool interface over screen-driving. Tools
+fail explicitly; scrapers fail silently and at the worst time.
+
+## Sequencing
+
+Build in this order: highest frequency × lowest complexity first. Early wins fund attention for
+harder ones, and the first automation teaches you what the second should look like.
+
+## Risks to state before building
+
+Data leaving your control, model output reaching customers unreviewed, a silent dependency on a
+vendor's pricing, and the maintenance burden landing on one person. Name the owner of each before
+building, not after.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Automate a process nobody has written down. You will automate the exceptions along with the work.
+- Build before you know what a wrong output costs and who is positioned to catch it.
+- Put a model where a rule would do. Deterministic steps should stay deterministic.
+- Ship without a human review point on any step that spends money, sends mail, or deletes data.

package/sources/headcount/plugins/technology/skills/ai-workflow-architect/references/sources.md

@@ -0,0 +1,17 @@
+# Sources — `technology:ai-workflow-architect`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## Model Context Protocol specification
+
+Model Context Protocol project · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://modelcontextprotocol.io/specification/latest>
+
+**Authoritative for:** The protocol between an agent host and a tool or resource server — message shapes, lifecycle, transports, and what a conformant server must implement.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.