chofex-hackathon

Hack the Andes

Use the andes CLI to act on the participant's behalf while keeping identity, consent, challenge direction, and final submission decisions with the participant.

Pace

Move quickly and proactively. Run routine, non-destructive setup, schema, status, and requirements commands without asking permission or narrating each command. Batch participant questions into the fewest practical turns. Pause only for:

• browser authentication;
• confirmation that the authenticated email belongs to the participant;
• application answers that are missing or genuinely ambiguous;
• the participant's own consent decisions;
• challenge experiment selection, continuation checkpoints, evidence review, and release judgment;
• final admission or challenge submission approval; and
• private accepted-participant details.

Mechanical formatting is not personal-data invention. Normalize obvious handles and domains, show the result in the final application summary, and let the participant correct it before submission:

• GitHub cuevaio or @cuevaio becomes https://github.com/cuevaio.
• LinkedIn cuevaio or @cuevaio becomes https://linkedin.com/in/cuevaio.
• A profile URL or bare domain missing a scheme gets https://.

Ask a follow-up only when the input is malformed or has more than one plausible meaning that would materially change the application. State low-risk parsing in a concise interpretation note immediately before the final summary instead of interrupting the interview. Preserve participant-provided wording and casing for personal answers.

Command setup

1. Check for the current CLI capabilities with andes --version and andes validate --help.
2. If either command is unavailable, install or upgrade proactively with npm install --global hacktheandes-cli@latest; do not delegate installation to the participant.
3. Verify both commands. If global installation is unsupported or fails for lack of permission, use npx --yes hacktheandes-cli@latest as the command prefix. When working inside the Hack the Andes repository, bun run --filter chofex-cli dev -- is also an acceptable fallback. Ask the participant for help only when installation requires an interactive administrator or credential step that the agent cannot perform.
4. Use --output json for every command the agent needs to interpret. JSON responses are versioned envelopes with ok, requestId, and either data or error.

Use one consistent command prefix for the whole session. The CLI already targets the Hack the Andes service, so use the default URL.

Authenticate the participant

Run:

andes --output json whoami

If authentication is required, ask the participant to run andes login in their own interactive terminal and finish the browser flow. Then run whoami again and ask them to confirm that the returned email is theirs. Login tokens belong in the operating-system credential store. Treat CHOFEX_TOKEN as a secret and keep it out of chat, command arguments, logs, and files.

Authentication is complete only when whoami succeeds and the participant confirms the email.

Apply

First, check whether the participant already has an application:

andes --output json status

If one exists, report its status and follow Next steps. Start an application when there is no application, resume and submit it when the status is draft, or let a rejected participant apply again. A rejected application remains in history. The participant may submit the application before completing a challenge, but the application alone never reserves a seat. Technical challenges are mandatory for admission, and organizers select the strongest engineers from their ranked results. Only the latest server-advertised challenge version counts; legacy attempts remain historical. Every selected engineer must also have a submitted application before being accepted.

Get a fresh input template instead of relying on a memorized schema:

andes schema --stage application

The output is an example shape, not an application draft. It contains every supported JSON key. Copy those keys exactly; for example, use fullName, role, phone, bio, portfolioUrl, and shippedProject. Never save or submit the example values.

Collect every field in one compact batch when practical. Accept a natural, unlabeled reply and map it using context; numbered formatting is optional. For open-ended fields, ask directly in chat or use an input whose selectable choices are actual answers such as “Omit.” A placeholder choice such as “Enter all answers” is not an answer and must not be offered. Ask only for fields the participant has not already answered. Group the questionnaire so the participant can scan and answer it naturally:

• required profile: full name, role, and country of residence;
• optional profile: phone number, bio, portfolio URL, something they have shipped, LinkedIn, and GitHub URLs; and
• required Terms and Conditions.

Explain these rules while collecting answers:

• Registration is for the in-person event in Lima, Peru. The application uses the authenticated account's primary email.
• fullName, role, and countryCode are required. Ask for the participant's country of residence and use its ISO two-letter code. Do not assume Peru.
• The participant chooses their country once. Only the organizers can correct it after reviewing LinkedIn or other social profiles. Reuse the saved country on reapplication. Existing participants with no country can select it with andes country --code PE, replacing PE with their actual country.
• Before submitting a country other than Peru, explain that the event is in Lima and participants outside Peru must cover their travel costs. Travel support is reserved for exceptional talent residing in Peruvian cities other than Lima. Do not promise travel support.
• Every field grouped under optional profile is optional.
• codeOfConductAccepted must be the participant's explicit true; an agent cannot consent for them.

Treat the fresh schema as authoritative. On local validation errors, use error.details.acceptedFields to correct payload keys. Inspect CLI source only when the schema and error details do not resolve the problem.

Before requesting required consent, give the participant this link:

• https://hacktheandes.com/terms

Ask for the Terms and Conditions decision by name. An agent cannot consent for the participant. If they do not accept, do not discard the answers already collected. Ask whether they want to cancel registration or read the document and explicitly accept it. Continue from the consent step if they accept; do not submit if they cancel.

Once every answer and consent choice is settled, submit the application. Do not claim success until registration.status is submitted. Create exactly one mode-600 temporary application file outside the project. On a POSIX system:

application_file="$(mktemp)"
chmod 600 "$application_file"
printf '%s\n' "$application_file"

Record the exact printed path and reuse it for every later operation. When shell state does not persist between commands, use that literal path; never guess, shorten, or replace it. One application uses one payload file, one recorded path, and one cleanup.

Write only participant-provided answers to that file and omit unanswered optional fields. Validate it locally before asking for submission approval:

andes --output json validate --stage application --input "$application_file"

Resolve validation errors before continuing. First state every low-risk interpretation or normalization in a concise note. Then show a readable summary of the exact validated payload, include every consent, and ask: Submit this application now? Run the submission only after an explicit yes given at this point.

andes --output json register --input "$application_file"

A successful submission returns status: "submitted". Keep the mode-600 temporary file through correctable validation failures so a retry does not require rebuilding it.

Work through challenges together

Challenge solving is a participant-directed conversation. Routine setup, reading the contract, and checking existing status or observations may proceed without interruption. Before spending queries or implementing a solution, explain the next hypothesis or change in plain language and ask the participant which direction to take. Wait for their reply before proceeding.

Keep each approved round small: one hypothesis, at most three new oracle queries, or one agreed implementation change with its free local tests. Explain what the inputs distinguish before querying. Do not launch a script that spends the whole query budget, chain multiple rounds, or continue solving in the background while waiting for the participant.

After each round, show the evidence, what it supports, what remains uncertain, and the remaining budgets. Ask the participant to choose the next hypothesis, change the plan, or stop. They may select a proposed option or say "continue" after a concrete next round has been described. Their reply authorizes only that round. A general "solve it for me", "keep going until finished", silence, or an earlier approval does not replace later checkpoints in this challenge workflow. Do not invent the participant's direction or answers.

Before every official evaluation, show the solution changes, free-test results, unverified assumptions, and remaining evaluation count. Ask whether to spend one evaluation on that exact solution and wait for an explicit reply. After the result, explain its limits and pause again before edits, more queries, or another evaluation. A notebook-perfect result does not prove hidden correctness; an aggregate score does not identify a missing rule.

These conversational checkpoints supplement the source-bound participant reviews required by Broken Agent and Slow Service. They do not replace those reviews or claim that the server verifies human involvement.

Black Box challenge

The Shipping Machine is one of the technical admission challenges. It does not block application submission, but challenge participation is mandatory to compete for a seat. Rankings—not the application prose alone—identify the strongest engineers, and organizers record acceptance manually on the submitted application. The challenge slug always resolves to the latest version; never use a historical attempt as completion. List challenges, then inspect the currently available challenge:

andes --output json challenge list
andes --output json challenge show --challenge black-box

AI tools are allowed. The oracle is personalized, so a leaked solution will not match this participant's function. Design experiments: change one variable at a time, look for thresholds, then test combinations such as fragile and express together. Each successful new input consumes one of 25 queries; duplicate or failed queries are free. Follow the participant-directed rounds above.

andes --output json challenge query --distance 1 --weight 1 --hour 12 --fragile false --express false
andes --output json challenge notebook --format json

After collecting observations, write function calculateShipping(input) in a local file. Test against the notebook (does not consume an official evaluation), then evaluate against the hidden set (limited to 3 official attempts):

andes --output json challenge test --source "$PWD/shipping.js"
andes --output json challenge evaluate --source "$PWD/shipping.js"

Never ask the participant to paste a solution that they did not run. Application submission and challenge completion are separate operations, but both belong to the admission path. Report application success only when the envelope has ok: true and registration.status is submitted. Never describe that state as waiting with no action: proceed to the open challenge and explain that a seat is earned through ranked challenge performance.

Public rankings are read-only:

andes --output json challenge ranking --challenge black-box

Broken Agent challenge

When the participant asks to solve, submit, or evaluate challenge 2 or broken-agent—including when the default andes challenge guide identifies Broken Agent—read and follow references/broken-agent.md. It defines the required human–agent reasoning loop and the source-bound review needed before an official evaluation.

Slow Service challenge

When the server lists challenge 3, make-it-fast, as open, read references/slow-service.md. Its canonical version is slow-service-v3. It uses source-bound companion review and browser/passkey approval of the exact implementation. AI help is allowed in both stages. Do not invent evidence or the participant's decision. The approval records responsibility, not proof of understanding or independent authorship. Check challenge list before starting; a closed challenge retains its ranking and historical results but does not accept new submissions.

Power Grid challenge

When the participant asks to solve challenge 4 or power-grid, or the server advertises it as available to their account, read references/power-grid.md. Apply the conversation checkpoints above throughout discovery, implementation, and evaluation.

Next steps

Read the application and server-calculated requirements together:

andes --output json status

The status response includes requirements. Run the separate requirements command only when the status response omits them or the participant specifically asks for requirements alone.

Interpret the returned state as follows:

• draft: this is an application left by an older CLI flow. Show requirements.parts and missing fields, collect the complete application, and use andes register to submit it. Then continue to the open mandatory admission challenge; do not delay application submission for challenge work.
• submitted, under_review, or waitlisted: report the exact status and requirements. Make clear that the application has been received but no seat is assigned. Run andes challenge list, identify the open challenge, and continue its required human–agent flow. Never tell the participant to merely wait while an admission challenge is open.
• rejected: show the review feedback when present. Offer a new application only if canSubmitNewApplication is true. Interactive andes register presents the rejected application's answers as editable defaults. Obtain a fresh submission approval rather than silently resubmitting old answers.
• accepted: congratulate the participant and explain any missing acceptance fields. Continue to Confirm attendance only when canSubmitAcceptedDetails is true.
• withdrawn: report the status and follow only the actions returned by the server.
• requirements stage complete: attendance details are complete. During the event, continue to team setup, progress updates and project submission as relevant.

Return the exact rejection reason, missing-field reasons, and server state. The server response is authoritative when it differs from this summary.

Confirm attendance

Acceptance details include the participant's full name exactly as it appears on their ID document, birth date, national ID or passport number, emergency contact, a required profile-picture confirmation, and other private information. The participant must explicitly choose their Clerk picture, their GitHub avatar, or a custom upload; never infer this choice from an available image. Recommend that the participant keep these values out of agent chat by running this themselves in an interactive terminal:

andes confirm

If the participant explicitly asks the agent to submit them instead, fetch a fresh template with andes schema --stage acceptance, collect every required value without guessing, store it in a mode-600 temporary file outside the project, and avoid printing its contents. dateOfBirth uses YYYY-MM-DD and must be a real date in the past. Shirt size is required for this in-person event. Validate the file with andes --output json validate --stage acceptance --input /path/to/private-attendance.json; the success response does not echo its contents. Resolve validation errors, then obtain a fresh Submit these private attendance details now? approval and run:

andes --output json confirm --input /path/to/private-attendance.json

When pictureSource is upload, ask for the image's path on the participant's computer and add --picture /that/path/image.png to the confirm command. Do not copy image bytes into the JSON file or chat. The CLI accepts JPEG, PNG, and WebP files up to 5 MB, waits for the upload and verification to finish, and displays upload progress on stderr. Custom uploads are available only after acceptance and are limited to five attempts per 24 hours.

Delete the file immediately after the command completes. Run status again and verify that the requirements stage is complete before reporting that attendance confirmation is done.

Build with your team and publish updates

During the event, read andes project --help and andes team --help before using these commands. Upgrade the CLI if the project commands are unavailable. Use andes --output json team and andes --output json project to learn the current team and submission. Use andes --output json project updates to read the update history. Any member can publish an update or edit the shared submission. Use the team name as the project name; rename it with andes --output json team rename --name "New team name" when requested. Never create another project name.

Help the team choose its next useful step. When direction is unclear, ask the questions that resolve the uncertainty, rather than running a fixed interview:

• Who has this problem, and what do they do today?
• What is the most important thing the product needs to do right now?
• What is blocking the team, and what concrete help would unblock it?
• Which decision did we make, what evidence supports it, and what did we leave out?
• What can a person actually try in the next demo?

At a meaningful milestone, a change of direction, a working demo, or a blocker that mentors could help with, inspect the latest shared update and suggest sending another if there is new information. During an active work session, check again after substantial progress or roughly an hour without a useful update. Do not send repetitive updates or interrupt every code change. This skill runs during active sessions; it does not create a background timer.

If the participant says "send an update to the mentors/judges", that authorizes preparing and publishing a factual update. Do not ask for the same permission again. If the agent only suggests an update, offer the draft and obtain the participant's go-ahead before publishing. Standing authorization from the participant in this session to publish progress updates also applies. Base the content on the work inspected and the participant's statements. Distinguish verified results from plans and unknowns. Never invent user tests, performance numbers, impact, or completed features.

A useful Markdown update says what changed, why the team chose it, what works, what is blocked, what help is needed, what was deployed, which tools or services the team used, and what comes next. Omit sections that have no useful information. Include relevant public demo links. Exclude secrets, tokens, private user data and confidential material. The update is shared with the organization and can become public in the project gallery with the author's public name and timestamp. Publishing saves a log for review; it does not send email or promise an immediate mentor response.

andes --output json project update --message "Terminamos el flujo y desplegamos la demo."
andes --output json project updates

Use direct text by default. For longer Markdown, project update --file /path/to/update.md is also supported; a file is optional. A successful update returns only the saved entry and the total. Use project updates to read the full history. Read the success envelope and verify the saved content before claiming it was published. If a write times out, inspect the history before retrying so that you do not append the same update twice.

The four event tracks are Clima y Territorio (environmental), Movilidad y Transporte (transport), Educación Escolar (education), and Seguridad (security). Mobility includes public transport within Lima and passenger transport, regional connections, freight and distribution in other regions. Each track allows 25% of the current team count, rounded up; the event has at most 36 teams overall. Existing track selections survive capacity reductions. Use andes team to read current availability and andes team track to select.

Submit and maintain the event project

Read the participant guide at https://hacktheandes.com/guide and the delivery conditions at https://hacktheandes.com/participation-terms for current event instructions. These project submissions are separate from admission applications and challenge submissions.

A project submission needs exactly these deliverables, using the existing team name:

• A live deployment URL for the working application.
• A presentation URL, such as Canva, Google Slides or a coded presentation.
• A GitHub repository URL, such as https://github.com/team/project. Read the Git remote to find it; confirm with the participant if the remote is ambiguous.
• A Markdown description explaining the problem, intended users, working solution and known limitations.

Participants cannot connect their laptops to the event's presentation equipment. The organization opens the submitted links on its own computer. Check both URLs from a signed-out or private browser session when possible. Verify that there are no access requests, personal login dependencies or local files. Do not claim a link is accessible unless you checked it. If access cannot be verified, tell the participant what remains to check.

Encourage an early submission once the four deliverables are ready. The same submission can be edited later, including one field at a time. Ask only for missing deliverables. Inspect the repository and current deployment to prepare an accurate Markdown description. Do not invent deployment or presentation URLs. An explicit request to submit or update the project authorizes that action; otherwise show the prepared submission and ask whether to submit it.

andes --output json project submit --deployment-url https://app.example --presentation-url https://slides.example --github-url https://github.com/equipo/proyecto --file /path/to/project.md
andes --output json project
andes --output json project submit --presentation-url https://new-slides.example

Check the returned saved submission, including every changed field. Any teammate can edit it, so read fresh state before acting and coordinate conflicting edits. If the last member leaves or joins another team, the old team dissolves and releases its track and capacity. The organization retains its submission and update history in a private archive. That archive is not part of the public gallery and does not transfer to the new team.

The public gallery at https://hacktheandes.com/projects starts hidden and opens when the organization enables it. Do not promise a Sunday opening time. Once published, a submitted project's page includes its description, URLs and update history. Remind the team to exclude private data from all of these fields.

Failures

On ok: false, report error.code, error.message, and requestId. Resolve local validation failures before showing the final summary. Correct mechanical issues directly when the participant's answers do not change; involve them when an answer or consent must change. For admission, attendance and challenge submissions, any payload change after final approval invalidates that approval: show the updated summary and ask again. Retry an unchanged failed request only when retryable is true. For admission, attendance and challenge submissions, obtain fresh submission approval before retrying. For authentication failures, return to Authenticate the participant. Preserve the request ID for support instead of claiming success or bypassing a failed state.