implement-feature
Skill393 starsChanged 37 days agoApache-2.0View on GitHub
Guide for implementing features in asc-swift (App Store Connect CLI) following architecture-first design, TDD, rich domain models, and Swift 6.2 patterns. Use this skill when: (1) Adding new functionality to the CLI tool (2) Creating domain models that follow user's mental model (3) Building new CLI commands that consume domain repositories (4) User asks "how do I implement X" or "add feature Y" (5) Implementing any feature that spans Domain, Infrastructure, and ASCCommand layers
27 other projects use a version of this.
Adopted by
Most recently taken up by
- Disthere/agentic-openspectheir own version, first seen Nov 16, 2026
- pankaj-mahaur/Agent-Daemontheir own version, first seen Nov 6, 2026
- tddworks/ClaudeBartheir own version, first seen Nov 3, 2026
- snuffish/dotfilestheir own version, first seen Nov 1, 2026
- mAzurkovic/skillstheir own version, first seen Nov 1, 2026
- olimstv/claude-skillstheir own version, first seen Nov 1, 2026
Used with
Projects with it also use prepare-release, create-skill and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
ShopifySkillprepare-release
Prepare the changeset-release/main branch for release by syncing version.ts files and running pnpm install
Also in 3 projects that use this
ElasticSkillcreate-skill
Interactively create a new Claude Code skill and add it to the elastic-docs-skills catalog. Use when the user wants to generate a new skill, scaffold a slash command, or build automation for docs tasks.
Also in 3 projects that use this
MicrosoftSkillplaywright-cli
Automate browser interactions, test web pages and work with Playwright tests.
Also in 3 projects that use this
VercelSkillfind-skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Also in 3 projects that use this
GoogleSkillcode-review
Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.
Also in 3 projects that use this
SentrySkillskill-creator
Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.
Also in 3 projects that use this
Other versions27 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 27
- Agenta-AI/agenta★ 4.9ksame name
- tddworks/ClaudeBar★ 1.6ksame name
- leonvanzyl/agentic-coding-starter-kit★ 447same name
- nockawa/Typhon★ 253same name
- tddworks/SkillsManager★ 165same name
- DGouron/review-flow★ 44same name
- kiminmonaco/ClaudeBar★ 8same name
- mgiovani/cc-arsenal★ 8same name
- leonvanzyl/claude-code-pro-workflow-demo★ 4same name
- 26zl/universal-agent-skills★ 3same name
17 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- app-implement-featureSkill
- fix-bugSkill
- improvementSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 1 is distinctive, and 10 are very specific to this project.
0
Common
Most of the 25 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 85
Nested CLI subcommands: when the CLI is asc iap price-points list (subcommand of iap), register the route key with the literal space: …
- Very specific: line 89
Every registerRoute(...) call must be reachable from RESTPathResolver.ensureInitialized().
- Very specific: line 240
Start by thinking like the user: "When I run asc my-models list --parent-id p-1, what should I see?"
- Distinctive: line 244
Before writing any code, write down the exact JSON the user should see.
- Very specific: line 267
Create a minimal command skeleton (struct + @Option fields + execute() returning "") — just enough to compile, NOT enough to pass.
- Very specific: line 294
Run it — must fail because execute() returns "".
- Very specific: line 298
Add makeMyRepository() to ClientProvider.swift + factory to ClientFactory.swift
- Very specific: line 301
Run swift test — all must pass
- Very specific: line 314
Make sure your model has Presentable conformance (so restFormat accepts it).
- Very specific: line 317
Add a controller in Sources/ASCCommand/Commands/Web/Controllers/<X>Controller.swift:
- Very specific: line 342
Add a REST test in Tests/ASCCommandTests/Commands/Web/RESTRoutesTests.swift that calls execute(repo:affordanceMode: .rest) and asserts …
“Common” is measured: kept by at least 6 in 10 of the 25 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Implement Feature in asc-swift
Implement features using architecture-first design, TDD, rich domain models, and Command Affordances.
Workflow
1. ARCHITECTURE DESIGN (Required — User Approval)
• Think from user's mental model → identify domain models + commands
• Analyze requirements, create ASCII diagram
• Present to user → wait for approval
2. TDD IMPLEMENTATION (Always write tests FIRST)
• NEVER write implementation code without a failing test
• Think from user's mental model — test cases describe what the user expects, not internals
• Write domain tests first → then infrastructure tests → then command tests
• Each test must FAIL (red) before writing implementation
• Domain tests → Domain value types + AffordanceProviding + @Mockable protocol
• Infrastructure: SDK adapter injecting parent IDs, composing multi-call flows
• Command: formatAgentItems → {"data":[{...,"affordances":{...}}]}
3. REST EXPOSURE (no feature is done until reachable via REST)
• Add affordanceMode parameter to execute(repo:)
• Wire a controller in Sources/ASCCommand/Commands/Web/Controllers/
• Register the route in RESTRoutes.swift
• Verify _links is populated for the parent resource
4. DOCS
• docs/features/<feature>/README.md (user-facing, ≤200 lines), one CHANGELOG line, make docsPhase 0: Architecture Design (MANDATORY)
See architecture-diagrams.md for diagram templates and the files-to-create table.
Steps:
- Identify new models, protocols, and SDK endpoints needed
- Draw the three-layer ASCII diagram
- Fill the component table (purpose / inputs / outputs / dependencies)
- Present with
AskUserQuestion— options: "Approve" / "Modify"
Do NOT write code until user approves.
Core Design Rules
1. Affordances: prefer structuredAffordances (single source of truth)
structuredAffordances: [Affordance] is the canonical source. Both the CLI string (affordances) and the REST _links (apiLinks) auto-derive from it. Do not override apiLinks directly — that bypasses SSOT and creates two parallel surfaces to maintain.
extension MyModel: AffordanceProviding {
public var structuredAffordances: [Affordance] {
var items: [Affordance] = [
Affordance(key: "listChildren", command: "children", action: "list",
params: ["parent-id": id]),
Affordance(key: "listSiblings", command: "my-models", action: "list",
params: ["grandparent-id": parentId]),
Affordance(key: "update", command: "my-models", action: "update",
params: ["model-id": id, "name": "<name>"]),
]
if isActionable {
items.append(Affordance(key: "doAction", command: "my-models", action: "action",
params: ["model-id": id]))
}
return items
}
}Param ordering caveat: Affordance.cliCommand sorts params alphabetically by key. Migration from a raw affordances override may shift the CLI string order — update existing test JSON snapshots to match. The CLI parser doesn't care about flag order.
Nested CLI subcommands: when the CLI is asc iap price-points list (subcommand of iap), register the route key with the literal space: command: "iap price-points". Both Affordance.cliCommand and RESTPathResolver use the same key, so they stay in sync.
2. REST routes register in two places
Every registerRoute(...) call must be reachable from RESTPathResolver.ensureInitialized(). Add _ = _yourRoutes there. Forgetting this means _links silently resolves to [:] because the route table is empty when the protocol's apiLinks derivation runs in tests / fresh process state.
3. Every domain model must
public struct MyModel: Sendable, Equatable, Identifiable, Codable {
public let id: String
public let parentId: String // always carry parent ID (ASC API omits it)
}See domain-models.md for complete patterns including:
- Parent ID injection in infrastructure mappers
- Semantic booleans on state enums
MockRepositoryFactoryusage- Domain operations — extension methods that take
repo: some Protocolto express what a model can do with its own ID (e.g.set.importScreenshots(entries:imageURLs:repo:))
See command-affordances.md for:
AffordanceProvidingprotocolformatAgentItemsvsformatItems- JSON output shape
{"data":[{...,"affordances":{...}}]}
4. Repository protocol — primitives only, but allow composition in adapters
@Mockable
public protocol MyRepository: Sendable {
func listMyModels(parentId: String) async throws -> [MyModel]
}Protocol methods stay primitive (one user-visible operation per method). The SDK adapter is allowed to compose multiple ASC API calls inside a single method when the user-visible operation requires it — see "Multi-call composition" below.
5. Command wiring — accept affordanceMode for REST reuse
struct MyList: AsyncParsableCommand {
@OptionGroup var globals: GlobalOptions
@Option(name: .long) var parentId: String
func run() async throws {
let repo = try ClientProvider.makeMyRepository()
print(try await execute(repo: repo))
}
func execute(
repo: any MyRepository,
affordanceMode: AffordanceMode = .cli
) async throws -> String {
let items = try await repo.listMyModels(parentId: parentId)
let formatter = OutputFormatter(format: globals.outputFormat, pretty: globals.pretty)
return try formatter.formatAgentItems(items, affordanceMode: affordanceMode)
}
}The REST controller calls the same execute(repo:affordanceMode: .rest) — no duplicate logic.
Multi-call composition in SDK adapters
When ASC paginates a relationship or splits a single user-visible resource across endpoints, compose them inside the SDK adapter. Apple's parent-endpoint include=foo truncates the relationship to ~10 entries — for full lists, hit the dedicated relationship endpoint with explicit limit. The iOS SDK does this for fetchAvailability, fetchPriceSchedule, fetchEqualizations, and others.
public func getAvailability(iapId: String) async throws -> Domain.InAppPurchaseAvailability {
// Two parallel calls — `include=availableTerritories` truncates to ~10.
async let availResponse = client.request(
APIEndpoint.v2.inAppPurchases.id(iapId).inAppPurchaseAvailability.get(parameters: .init())
)
async let terrResponse = client.request(
APIEndpoint.v1.inAppPurchaseAvailabilities.id(iapId).availableTerritories.get(
fieldsTerritories: [.currency], limit: 200
)
)
let (avail, terr) = try await (availResponse, terrResponse)
let territories = terr.data.map { Domain.Territory(id: $0.id, currency: $0.attributes?.currency) }
return Domain.InAppPurchaseAvailability(
id: avail.data.id, iapId: iapId,
isAvailableInNewTerritories: avail.data.attributes?.isAvailableInNewTerritories ?? false,
territories: territories
)
}Test these with StubAPIClient.willReturn(_:) once per response type. The stub keys responses by String(describing: T.self), so each willReturn for a different response type queues up the next call's return value. Adding a regression test that returns 175 entries proves pagination works.
TDD Workflow
ALWAYS write tests first, then implement. Never write implementation code without a failing test. This is non-negotiable.
See tdd-patterns.md for complete patterns including:
MockRepositoryFactory(always use, never construct models inline)- Affordance tests
- Infrastructure parent-ID injection tests
@Mockable/given().willReturn()usage
Name each test should <outcome> [when <situation>], in the words of the person, agent or REST client who sees the result — never a method, type or mechanism verb → Naming tests.
Phase 1: Domain
@Test func `should belong to the parent it was listed under`() {
let model = MockRepositoryFactory.makeMyModel(id: "m1", parentId: "p1")
#expect(model.parentId == "p1")
}
@Test func `should point to its children on the CLI`() {
let model = MockRepositoryFactory.makeMyModel(id: "m1", parentId: "p1")
#expect(model.affordances["listChildren"] == "asc children list --parent-id m1")
}
@Test func `should point to its children over REST`() {
let model = MockRepositoryFactory.makeMyModel(id: "m1", parentId: "p1")
#expect(model.apiLinks["listChildren"]?.href == "/api/v1/my-models/m1/children")
#expect(model.apiLinks["listChildren"]?.method == "GET")
}Both affordances and apiLinks derive from the same structuredAffordances — testing each catches both the CLI and REST surfaces in one set of assertions.
Phase 2: Infrastructure
@Test func `should tie each model to the parent it was listed under`() async throws {
let stub = StubAPIClient()
stub.willReturn(makeFixture())
let repo = SDKMyRepository(client: stub)
let models = try await repo.listMyModels(parentId: "p-42")
#expect(models.allSatisfy { $0.parentId == "p-42" })
}For multi-call adapters, stub each response type:
@Test func `should show the thing together with its related items`() async throws {
let stub = StubAPIClient()
stub.willReturn(ThingResponse(data: ..., links: .init(this: "")))
stub.willReturn(RelatedResponse(data: [...], links: .init(this: "")))
let repo = SDKMyRepository(client: stub)
let result = try await repo.getThing(id: "t-1")
// assert the composed result
}Phase 3: Command
Start by thinking like the user: "When I run asc my-models list --parent-id p-1, what should I see?"
Step 1: Define what the user expects
Before writing any code, write down the exact JSON the user should see. This is your specification:
{
"data" : [
{
"id" : "m-1",
"parentId" : "p-1",
"affordances" : {
"listChildren" : "asc children list --parent-id m-1",
"listSiblings" : "asc my-models list --grandparent-id p-1"
}
}
]
}Affordances sort alphabetically by key in the JSON output, and params within each affordance sort alphabetically by flag name. Match that ordering in your expected JSON snapshot.
Also think about affordances from the user's perspective: "What can I do next?" — these are the commands the user would naturally want to run after seeing this output.
Step 2: Write the test (red)
Create a minimal command skeleton (struct + @Option fields + execute() returning "") — just enough to compile, NOT enough to pass. Then write the test:
@Test func `should list my models with their parent and next commands`() async throws {
let mockRepo = MockMyRepository()
given(mockRepo).listMyModels(parentId: .any).willReturn([
MockRepositoryFactory.makeMyModel(id: "m-1", parentId: "p-1")
])
let cmd = try MyList.parse(["--parent-id", "p-1", "--pretty"])
let output = try await cmd.execute(repo: mockRepo)
#expect(output == """
{
"data" : [
{
"affordances" : {
"listChildren" : "asc children list --parent-id m-1",
"listSiblings" : "asc my-models list --grandparent-id p-1"
},
"id" : "m-1",
"parentId" : "p-1"
}
]
}
""")
}Run it — must fail because execute() returns "".
Step 3: Implement and wire (green)
- Add
makeMyRepository()toClientProvider.swift+ factory toClientFactory.swift - Implement
execute()— just enough to make the test pass - Register in
ASC.swiftsubcommands array - Run
swift test— all must pass
Test rules
- Name = user expectation —
`should offer submit for review when the version is editable`, not`execute returns correct JSON`; pair it with the counterpart (`should not offer submit for review when the version is live`) - Always
#expect()—_ = try await cmd.execute(...)with no assertion is not a test - Exact JSON assertion — assert the complete output string, never
output.contains(...). This verifies field names, field order, affordance content, and nil-field omission all at once - Think about edge cases from user's perspective — "What if there are no results?", "What if the version is not editable — should submit still appear?"
Phase 4: REST exposure (mandatory)
Per CLAUDE.md, a feature is not complete until it is reachable via REST. Steps:
- Make sure your model has
Presentableconformance (sorestFormataccepts it). - Confirm
structuredAffordancesis in place (so_linksauto-populates for the parent resource that lists this model). - Confirm the relevant route is registered AND touched in
RESTPathResolver.ensureInitialized(). Add a controller in
Sources/ASCCommand/Commands/Web/Controllers/<X>Controller.swift:struct MyController: Sendable { let repo: any MyRepository func addRoutes(to group: RouterGroup<BasicWebSocketRequestContext>) { group.get("/parents/:parentId/children") { _, context -> Response in guard let parentId = context.parameters.get("parentId") else { return jsonError("Missing parentId") } let items = try await self.repo.listMyModels(parentId: parentId) return try restFormat(items) } } }Wire the controller in
Sources/ASCCommand/Commands/Web/RESTRoutes.swift:if let myRepo = try? factory.makeMyRepository(authProvider: auth) { MyController(repo: myRepo).addRoutes(to: v1) }- Advertise the resource from
APIRoot.structuredAffordances(Sources/Domain/Shared/APIRoot.swift) when it is a new top-level resource, soGET /api/v1lists it. - Add a REST test in
Tests/ASCCommandTests/Commands/Web/RESTRoutesTests.swiftthat callsexecute(repo:affordanceMode: .rest)and asserts_links+ the resolved REST path. - Smoke-test the live server. Build (
swift build), restart (asc web-server), andcurlthe parent resource — confirm_linksfor each item points at the new endpoint.
REST rules:
- CLI flag and REST query-param names match:
--expired-only↔?expired-only=true, both calling the same repository method. - Helpers in
RESTRoutes.swift:restFormat(items)(REST twin offormatAgentItems(…, affordanceMode: .rest)) andjsonError(message, status:)(fromInfrastructure/Web/ASCWebServer.swift). RESTPathResolvermaps affordance actions to HTTP:list/get→ GET,create/add→ POST to the parent's collection,update→ PATCH,delete/remove→ DELETE, anything else (e.g.submit) → POST…/{id}/{action}.- Controllers are structs with dependencies injected at init; repositories are constructed once in
RESTRoutes.configure, never per request.
Phase 5: Docs
Docs follow docs/documentation-design/README.md: each fact has one home, and nothing repeats --help or the source.
docs/features/<feature>/README.md— user-facing, ≤200 lines, written from the actual implementation (read the code, never write from memory):- frontmatter
description:— one sentence, what + "Use when …", ≤250 chars (it becomes the docs index row) - Quick start → Workflows → REST (paths + query-param mapping) → Gotchas → See also
- No flag tables (
docs/commands.mdis generated), architecture, domain model listings, file maps or test snippets. Non-obvious reasons (Apple caps, multi-call workarounds) go in Gotchas as one-liners. - Examples use placeholders (
1234567890,ver-1,sub-1), never IDs, names or text copied from a real account. - A topic that doesn't fit goes into
docs/features/<feature>/<topic>.mdnext to the README. - Example:
docs/features/testflight/README.md.
- frontmatter
CHANGELOG.md— one bullet under[Unreleased], ≤300 chars: starts with what the user types, says the effect (not the implementation), ends with→ [docs](docs/features/<feature>/README.md)and the PR link. Implementation detail goes in the PR.make docs— regeneratesdocs/commands.mdand thedocs/README.mdindex. Never edit those by hand.- README.md — only if the feature is a new row in its "What It Covers" table.
make check-docs— no broken links, within budgets.
Anti-patterns (don't)
- ❌ Override
apiLinksdirectly. UsestructuredAffordancesso CLI and REST stay in sync. The protocol's defaultapiLinksderivation handles the REST mapping for you. - ❌ Override
affordanceswith raw strings when migrating. That blocks the default-derivation path. If you need a CLI string theAffordancerenderer can't produce (e.g. multi-value flags like--territory USA --territory CHN), simplify the affordance — pick one representative value — rather than maintaining two surfaces. - ❌
include=relationshipfor full lists. Apple paginates the included relationship to ~10 entries. Use the dedicated relationship endpoint with explicitlimit:. - ❌
output.contains(...)in command tests. Always assert the full JSON string so you catch field renames, ordering changes, and nil-omission regressions. - ❌ Forgetting
_ = _yourRoutesinRESTPathResolver.ensureInitialized(). Tests pass locally because some other model touched the lazy first; live/api/v1/...returns empty_links. - ❌ Skipping the smoke test. Tests can pass while
_linksis empty in production due to test-time route side-effects. Alwayscurlthe live endpoint after restart.
References
- Architecture diagrams — templates, command tree, files table
- Domain model patterns — model requirements, parent IDs, mappers, MockRepositoryFactory
- Command Affordances — AffordanceProviding, formatAgentItems, JSON shape
- TDD patterns — MockRepositoryFactory, affordance tests, async patterns
- Swift concurrency — Sendable, @unchecked Sendable, method naming
Checklist
Phase 0: Architecture
- Requirements analyzed
- ASCII diagram created (see architecture-diagrams.md template)
- Files table filled
- User approval received
Phase 1: Domain
XModel.swift—struct+Sendable+Equatable+Identifiable+Codable- Carries
parentId(ASC API omits parent IDs from response — Infrastructure injects them) Presentableconformance (tableHeaders,tableRow)AffordanceProvidingviastructuredAffordances(NOT rawaffordances)- State enum with semantic booleans (
isLive,isEditable,isPendingReview, etc.) XRepository.swift—@Mockableprotocol with primitive methods onlymake*factory added toMockRepositoryFactory.swift- Domain tests: model fields, semantic booleans, affordances, and
apiLinksfor the new keys
Phase 2: Infrastructure
SDKXRepository.swift— implements protocol, injects parent IDs in mappers- Multi-call composition where needed (relationships paginate at ~10 — use dedicated endpoints with
limit:) - Factory registered in
ClientFactory.swift _xRoutesregistered AND touched inRESTPathResolver.ensureInitialized()- Infrastructure tests cover: parent ID injection, multi-call composition, >10-entry regression
Phase 3: Command
XCommand.swift+ subcommands usingformatAgentItemsexecute(repo:affordanceMode: .cli)— accepts mode for REST reuseClientProvider.swift— static factory method- Registered in
ASC.swiftsubcommands array - Command tests:
should …names, always#expect(), exact JSON snapshot - Affordance keys sort alphabetically; params within each affordance sort alphabetically — match this in JSON snapshots
Phase 4: REST exposure
- Controller added under
Sources/ASCCommand/Commands/Web/Controllers/ - Wired in
Sources/ASCCommand/Commands/Web/RESTRoutes.swift - New top-level resource advertised in
APIRoot.structuredAffordances - REST query-param names match the CLI flags
- REST test in
RESTRoutesTests.swift— callsexecute(repo:affordanceMode: .rest), asserts"_links"+ resolved path - Smoke-tested live server — restarted and curl'd the parent resource;
_linksconfirms the new endpoint URL
Phase 5: Docs
docs/features/<feature>/README.mdwithdescription, written from actual code, ≤200 lines- REST section with path table + query-param mapping
- No flag tables, architecture, domain listings or file maps
make docsrun;make check-docsclean for the new files- CHANGELOG.md entry under
[Unreleased]
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

