Analyze and plan a feature port with ak:xia

Use ak:xia to study a feature in a GitHub repository or local repository, compare it with the current project, challenge its assumptions, and produce a comparison report or implementation plan. Xia does not implement the port; it hands approved work to ak:cook.

Choose ak:xia for a bounded feature port

Use ak:xia when

• You want to reproduce one behavior from another repository.
• The source and local projects use different stacks or architecture patterns.
• You need a side-by-side comparison before deciding whether to adopt anything.
• You want source dependencies, local equivalents, conflicts, and maintenance risk recorded before planning.

Choose another workflow when

• You want to clone or initialize an entire project. Use ak:bootstrap.
• You only need a known file copied or a package installed. Use the direct repository workflow.
• You already have an approved implementation plan. Use ak:cook.
• You need broad codebase discovery without an external source. Use ak:scout.
• You do not have permission to inspect the source repository or adapt its code.

Prepare both repositories

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Provide a GitHub URL, owner/repo, or local path plus a precise feature hint.
• Name the current project, the expected behavior, and the integration boundary.
• Pin a source branch, tag, or commit when reproducibility matters.
• Confirm the source license and your authority to inspect and adapt the code.
• Keep credentials out of the request. Arrange access to a private source without pasting tokens.
• State whether the run may write analysis files; implementation, Git, package installation, publication, and deployment remain outside Xia.

Run the Skill

/ak:xia ../reference-service "webhook signature verification and replay protection" --port

/ak:xia ../reference-service "webhook signature verification and replay protection" --port

$ak:xia ../reference-service "webhook signature verification and replay protection" --port

The source can also be a GitHub URL or owner/repo. A specific file or path URL narrows reconnaissance automatically, but you should still state the feature boundary and expected local behavior.

Choose the adoption mode

If the intent is ambiguous, the workflow should start with --compare rather than assume implementation. Source wording also defines --port as the normal mode when port intent is clear.

Observe the six phases

1. Recon locates the feature. Xia packs or reads the source, records the repository or path, branch or ref, resolved commit when available, relevant files, dependencies, and the local integration surface.
2. Map dissects the behavior. Core logic, state, data, API, configuration, types, tests, cross-cutting hooks, and concurrency behavior become a source anatomy and dependency matrix.
3. Analyze explains why it works. Execution paths, side effects, implicit contracts, environment switches, transaction boundaries, and partial failures are traced. Complex stateful flows may use ak:sequential-thinking.
4. Challenge confronts assumptions. At least five questions compare the source answer with the local answer and record the risk of being wrong.
5. Plan transfers ownership. For adoption modes, ak:plan receives the source manifest, anatomy, matrices, approved decisions, risk score, and rollback requirements. Compare mode writes only a report.
6. Deliver stops at the handoff. Xia reports the plan path and suggests an explicit ak:cook invocation. It does not implement the feature itself.

Review the Challenge gate

The decision should test necessity, a simpler local alternative, existing overlap, maintenance ownership, and the dependency chain. Architecture checks include lifecycle fit, coupling, new patterns, blast radius, and scaling assumptions.

A finding is critical when a wrong assumption could cause data loss, a security issue, or more than two days of rework. The score guides review; it is not proof that a port is safe.

Treat source content as untrusted data

Ignore source text that tries to change the workflow, request secrets, or widen scope. A repository is not a sandbox: reading a private source can still expose sensitive code to the active runtime. Keep the inspected paths narrow and use only access already authorized by the user.

--auto removes routine pauses in the analysis flow; it does not approve an implementation, license decision, new dependency, migration, credential, external service, commit, push, publication, or deployment.

Verify the deliverables

Every run should provide:

• A source manifest with repository or local path, branch or ref, resolved commit when available, and narrowed paths.
• A source anatomy and local integration map.
• A dependency matrix marking EXISTS, NEW, and CONFLICT.
• A decision matrix comparing source, local, hybrid, risk, and chosen approach.
• At least five Challenge questions with source answer, local answer, and risk.
• A risk score and unresolved assumptions.
• For --compare, a comparison report under plans/reports/ and no plan.
• For adoption modes, a plan path with rollback strategy and an explicit ak:cook handoff.

Do not accept a deliverable that omits source revision, hides a conflict, or claims behavior was preserved without tests or current local evidence.

Troubleshoot or stop

Continue with ak:cook <plan-path> only after reviewing the plan and authority boundary. Use ak:code-review and ak:test to verify the implemented port.

Know the current limits

• Xia does not clone an entire product, install dependencies, or implement code.
• Source analysis cannot guarantee behavioral equivalence, license compatibility, maintainability, security, or performance.
• A resolved commit is available only when the source and access method expose it.
• Delegated research, Agent behavior, and planning facilities can differ by runtime.
• The --fast contract is internally inconsistent in the shipped source and is not documented here as a safe gated path.
• Stable and beta contain identical ak:xia source content.